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Chapter 1: Getting started with Perl 
Language 


Version Release Notes Release Date 


1.000 1987-12-18 
2.000 1988-06-05 
3.000 1989-10-18 
4.000 1991-03-21 
5.000 1994-10-17 
5.001 1995-05-13 
5.002 1996-02-29 
5.003 1996-06-25 


5.004 perl5004delta 1997-05-15 
5.005 perl5005delta 1998-07-22 
5.6.0  perl56delta 2000-03-22 
5.8.0  perl58delta 2002-07-18 


perl581 delta, 
perl582delta, 
perl583delta, 
perl584delta, 2006-02-01 
perl585delta, 
perl58édelta, 
perl587delta, 
perl588delta 


5.10.0 perl5100delta 2007-12-18 


5.8. 


ee) 


5.12.0 perl5120delta 2010-04-12 
5.14.0 perl5140delta 2011-05-14 
5.16.0 perl5160delta 2012-05-20 
5.18.0 perl5180delta 2013-05-18 
5.20.0 perl5200delta 2014-05-27 
5.22.0 perl5220delta 2015-06-01 
5.24.0 perl5240delta 2016-05-09 
5.26.0 perl5260delta 2017-05-30 


Section 1.1: Getting started with Perl 


Perl tries to do what you mean: 
print "Hello World\n"; 


The two tricky bits are the semicolon at the end of the line and the \n, which adds a newline (line feed). If you have 
a relatively new version of perl, you can use say instead of print to have the carriage return added automatically: 


Version = 5.10.0 


use feature ‘say’; 
say "Hello World"; 


The say feature is also enabled automatically with a use v5.19 (or higher) declaration: 


use v5.10; 
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say "Hello World"; 





It's pretty common to just use perl on the command line using the -e option: 


S$ perl -e ‘print "Hello World\n"' 
Hello World 


Adding the -1 option is one way to print newlines automatically: 


$ perl -le ‘print "Hello World"' 
Hello World 


Version = 5.10.0 


If you want to enable new features, use the -E option instead: 





$ perl -E ‘say "Hello World"' 
Hello World 


You can also, of course, save the script in a file. Just remove the -e command line option and use the filename of 
the script: perl script.pl. For programs longer than a line, it's wise to turn on a couple of options: 


use strict; 
use warnings; 


print "Hello World\n"; 


There's no real disadvantage other than making the code slightly longer. In exchange, the strict pragma prevents 
you from using code that is potentially unsafe and warnings notifies you of many common errors. 


Notice the line-ending semicolon is optional for the last line, but is a good idea in case you later add to the end of 
your code. 


For more options how to run Perl, see perlrun or type perldoc perlrun at a command prompt. For a more detailed 
introduction to Perl, see perlintro or type perldoc perlintro at a command prompt. For a quirky interactive 
tutorial, Try Perl. 
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Chapter 2: Comments 


Section 2.1: Single-line comments 
Single-line comments begin with a pound sign # and go to the end of the line: 


# This is a comment 


my $foo = "bar"; # This is also a comment 


Section 2.2: Multi-line comments 


Multi-line comments start with = and with the =cut statement. These are special comments called POD (Plain Old 
Documentation). 


Any text between the markers will be commented out: 


=begin comment 


This is another comment. 
And it spans multiple lines! 


=end comment 


=cut 
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Chapter 3: Variables 


Section 3.1: Scalars 


Scalars are Perl's most basic data type. They're marked with the sigil $ and hold a single value of one of three types: 


e a number (3, 42, 3.141, etc.) 
e astring ('hi', "abc", etc.) 
e a reference to a variable (see other examples). 


my Sinteger = 3; # number 
my $string = "Hello World"; # string 
my Sreference = \Sstring; # reference to Sstring 


Perl converts between numbers and strings on the fly, based on what a particular operator expects. 


my $number = '41'; # string '41' 

my meaning = $number + 1; # number 42 

my Ssadness = '20 apples'; # string '2@ apples' 

my Sdanger = Ssadness * 2; # number '4@', raises warning 


When converting a string into a number, Perl takes as many digits from the front of a string as it can —- hence why 28 
apples is converted into 28 in the last line. 


Based on whether you want to treat the contents of a scalar as a string or a number, you need to use different 
operators. Do not mix them. 


# String comparison # Number comparison 
‘Potato’ eq 'Potato'; 42 == 42; 

‘Potato’ ne 'Pomato'; AQ RERA: 

'Camel' lt '‘Potato'; Aiea A2 

'Zombie' gt 'Potato'; ASAD: 

# String concatenation # Number summation 
'Banana' . 'phone'; 23 t I9: 

# String repetition # Number multiplication 
dnan X 3 6 a7? 


Attempting to use string operations on numbers will not raise warnings; attempting to use number operations on 
non-numeric strings will. Do be aware that some non-digit strings such as 'inf', 'nan', '@ but true’ count as 
numbers. 


Section 3.2: Array References 
Array References are scalars ($) which refer to Arrays. 


my @array = ("Hello"); # Creating array, assigning value from a list 
my Sarray_reference = \@array; 


These can be created more short-hand as follows: 
my Sother_array_reference = ["Hello"]; 


Modifying / Using array references require dereferencing them first. 
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my @contents = @{ Sarray_reference }; # Prefix notation 
my @contents = @Sarray_reference; # Braces can be left out 


Version = 5.24.0 


New postfix dereference syntax, available by default from v5.24 


use v5.24; 
my @contents = Sarray_reference->@*; # New postfix notation 


When accessing an arrayref's contents by index you can use the -> syntactical sugar. 


qw(one two three); my Sarrayref = | qw(one two three) | 


my @array = 
= Sarray[@]; my Sone = Sarrayref->[@]; 


my Sone 
Unlike arrays, arrayrefs can be nested: 


my @array = ( (1, ©), (©, 1) ) # ONE array of FOUR elements: (1, @, O, 1) 

my @matrix = ( [1, 9], [@, 1] ) # an array of two arrayrefs 

my Smatrix = [ [@, 1], [1, Ə] ] # an arrayref of arrayrefs 

# There is no namespace conflict between scalars, arrays and hashes 

# so @matrix and Smatrix _both_ exist at this point and hold different values. 


my @diagonal_1 = (Smatrix[@]->[1], Smatrix[1]->[0]) # uses @matrix 
my @diagonal_2 = (Smatrix->[@]->[1], Smatrix->[1]->[0]) # uses Smatrix 
# Since chained []- and {}-access can only happen on references, you can 
# omit some of those arrows. 

my Scorner_1 = Smatrix[@][1]; # uses @matrix; 

my Scorner_2 = Smatrix->[9][1]; # uses Smatrix; 


When used as Boolean, references are always true. 


Section 3.3: Scalar References 


A reference is a scalar variable (one prefixed by $ ) which “refers to” some other data. 


my $value = "Hello"; 
my Sreference = \Svalue; 
print $value; # => Hello 


print Sreference; # => SCALAR(@x268331@) 


To get the referred-to data, you de-reference it. 


say ${Sreference} ; # Explicit prefix syntax 
say SSreference; # The braces can be left out (confusing) 
Version = 5.24.0 


New postfix dereference syntax, available by default from v5.24 


use v5.24; 
say Sreference->$*; # New postfix notation 


This "de-referenced value" can then be changed like it was the original variable. 


${Sreference} =~ s/Hello/World/; 
print ${Sreference}; # => World 
print $value; # => World 
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A reference is always truthy — even if the value it refers to is falsy (like 8 or ""). 


You may want a Scalar Reference If: 
e You want to pass a string to a function, and have it modify that string for you without it being a return value. 


e You wish to explicitly avoid Perl implicitly copying the contents of a large string at some point in your function 
passing ( especially relevant on older Perls without copy-on-write strings ) 


e You wish to disambiguate string-like values with specific meaning, from strings that convey content, for 
example: 
o Disambiguate a file name from file content 


o Disambiguate returned content from a returned error string 


e You wish to implement a lightweight inside out object model, where objects handed to calling code don't 
carry user visible metadata: 


our %objects; 
my Snext_id = ð; 


sub new { 
my Sobject_id = Snext_id++; 
Sobjects{ Sobject_id } = { ... }; # Assign data for object 


my Sref = \Sobject_id; 
return bless( Sref, "MyClass" ); 


Section 3.4: Arrays 


Arrays store an ordered sequence of values. You can access the contents by index, or iterate over them. The values 
will stay in the order you filled them in. 


my @numbers_to_ten = (1,2,3,4,5,6,7, ' 
my @êchars-of hello = (ih ,-e , i, mlo 
my @word_list = ('Hello','World'); 


10); # More conveniently: (1..1@) 
D 


# Note the sigil: access an @array item with $array[index] 
my $second_char_of_hello = Schars_of_hello[1]; # 'e' 


# Use negative indices to count from the end (with -1 being last) 
my $last_char_of_hello = $chars_of_hello[-1]; 


# Assign an array to a scalar to get the length of the array 
my $length_of_array = @chars_of_hello; # 5 


# You can use $# to get the last index of an array, and confuse Stack Overflow 
my Slast_index_of_array = $#chars_of_hello; # 4 


# You can also access multiple elements of an array at the same time 

# This is called "array slice" 

# Since this returns multiple values, the sigil to use here on the RHS is @ 
my @some_chars_of_hello = @chars_of_hello[1..3]; # ('H', 'e', '1') 

my @out_of_order_chars = @chars_of_hello[1,4,2]; # (‘e', ‘o', 1) 


# In Python you can say array[1:-1] to get all elements but first and last 

# Not so in Perl: (1..-1) is an empty list. Use $# instead 

my @empty_list = @chars_of_hello[1..-1]; A) 

my @inner_chars_of_hello = @chars_of_hello[1..$#chars_of_hello-1]; # ('e','1','1') 
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# Access beyond the end of the array yields undef, not an error 
my Sundef = Schars_of_hello[6]; # undef 


Arrays are mutable: 


use utf8; # necessary because this snippet is utf-8 


Schars_of_hello[1] = 'u'; # (Cae pe le pO), 

push @chars of hello, (15, TID); # C a A ne A TE 

pop @chars_of_hello; # Gae e O a 

shift @chars_of_hello; # CC peg O ge 

unshift @chars_of_hello, ('j', HN); eH A tabi g. Weg abs gy dle FO PY) 
@charszof_hellol[2..5]°=(G@i0) j,k A ie 4 OC ihe OF EA under, !” whoops! 
delete Schars_of_hello[-2]; fe (A a Oe ee A cles) 


# Setting elements beyond the end of an array does not result in an error 
# The array is extended with undef's as necessary. This is "“autovivification. " 
my @array; # () 


my @array[3] = 'x'; # (undef, undef, undef, 'x') 
Finally, you can loop over the contents of an array: 


use v5.10; # necessary for 'say' 
for my Snumber (@numbers_to_ten) { 
say $number ** 2; 


} 


When used as booleans, arrays are true if they are not empty. 


Section 3.5: Typeglobs, typeglob refs, filehandles and 
constants 


A typeglob «foo holds references to the contents of global variables with that name: $foo, @foo, $foo, &foo, etc. You 
can access it like an hash and assign to manipulate the symbol tables directly (evil!). 


use v5.10; # necessary for say 


oun Sfea = “foo”: 

our bar; 

say ref *foo{SCALAR}; # SCALAR 
say S{ *foo{SCALAR} }; # bar 
*bar = *foo; 

say Sbar; # bar 
bar = 'egg'; 

say Sfoo; # egg 


Typeglobs are more commonly handled when dealing with files. open, for example, produces a reference to a 
typeglob when asked to create a non-global filehandle: 


use v5.10; # necessary for say 
open(my Slog, '> utf-8', '/tmp/log') or die $!; # open for writing with encoding 
say $log ‘Log opened’ ; 


# You can dereference this globref, but it's not very useful. 
say ref Slog; # GLOB 
say (*{$log}->{10} // ‘undef'); # undef 


close $log or die $!; 
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Typeglobs can also be used to make global read-only variables, though use constant is in broader use. 


# Global constant creation 
TRUE = NCW) 


our STRUE; 
say STRUE; # 7 
STRUE = ''; # dies, "Modification of a read-only value attempted" 


# use constant instead defines a parameterless function, therefore it's not global, 
# can be used without sigils, can be imported, but does not interpolate easily. 
use constant (FALSE => @); 

say FALSE; # 0 

say &FALSE; # 0 

say "S{\FALSE}"; # @ (ugh) 

say *FALSE{CODE}; # CODE(@xMA1DBABE ) 


# Of course, neither is truly constant when you can manipulate the symbol table... 
TRUE = Vi 2 


use constant (EVIL => 1); 
*FALSE = *EVIL; 


Section 3.6: Sigils 
Perl has a number of sigils: 


Sscalar = 1; # individual value 

@array = (1, 2, 3, 4, 5 ); # sequence of values 

%hash = (‘it', ‘ciao’, ‘en', ‘hello', ‘fr', ‘salut'); # unordered key-value pairs 
&function('arguments'); # subroutine 

*typeglob; # symbol table entry 


These look like sigils, but aren't: 


\@array; # \ returns the reference of what's on the right (so, a reference to @array) 
S#array; # this is the index of the last element of @array 


You can use braces after the sigil if you should be so inclined. Occasionally, this improves readability. 
say S{value} = 5; 


While you use different sigils to define variables of different types, the same variable can be accessed in different 
ways based on what sigils you use. 


%hash ; # we use % because we are looking at an entire hash 
Shash{it}; # we want a single value, however, that's singular, so we use $ 
Sarray[@]; # likewise for an array. notice the change in brackets. 
@array[9,3]; # we want multiple values of an array, so we instead use @ 
@hash{'it','en'}; # similarly for hashes (this gives the values: ‘ciao', ‘hello') 
*hash{'it', 'fr'}; # we want an hash with just some of the keys, so we use % 

# (this gives key-value pairs: ‘it', ‘ciao’, ‘fr', 'salut') 


This is especially true of references. In order to use a referenced value you can combine sigils together. 


my @array = 1..5; # This is an array 

my Sreference_to_an_array = \@array; # A reference to an array is a singular value 

push @array, 6; # push expects an array 

push @Sreference_to_an_array, 7; # the @ sigil means what's on the right is an array 


# and what's on the right is Sreference_to_an_array 
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# hence: first a @, thena $ 


Here's a perhaps less confusing way to think about it. As we saw earlier, you can use braces to wrap what's on the 
right of a sigil. So you can think of @{} as something that takes an array reference and gives you the referenced 
array. 


# pop does not like array references 

pop Sreference_to_an_array; # ERROR in Perl 5.20+ 
# but if we use @{}, then... 

pop @{ Sreference_to_an_array }; # this works! 


As it turns out, @{} actually accepts an expression: 


my Svalues = undef; 
say pop @{ Svalues }; # ERROR: can't use undef as an array reference 
say pop @{ Svalues // [5] } # undef // [5] gives [5], so this prints 5 


..and the same trick works for other sigils, too. 


# This is not an example of good Perl. It is merely a demonstration of this language feature 
my Shashref = undef; 
for my Skey ( %{ Shashref // {} } ) { 

"This doesn't crash"; 


} 
..but if the "argument" to a sigil is simple, you can leave the braces away. 


say $Sscalar_reference; 
say pop @Sarray_reference; 
for keys (%Shash_reference) { ... }; 


Things can get excessively extravagant. This works, but please Perl responsibly. 


my %hash = (it => ‘ciao’, en => 'hi', fr => ‘salut'); 
my Sreference = \%hash; 
my Sreference_to_a_reference = \Sreference; 


my Sitalian = Shash{it}; # Direct access 
my @greets = @Sreference{'it', ‘en'}; # Dereference, then access as array 
my %subhash = %$Sreference_to_a_reference{'en', 'fr'} # Dereference x2 then access as hash 


For most normal use, you can just use subroutine names without a sigil. (Variables without a sigil are typically called 
"barewords".) The & sigil is only useful in a limited number of cases. 


e Making a reference to a subroutine: 


sub many_bars { 'bar' x $_[9] } 
my $reference = \&many_bars; 
say Sreference->(3); # barbarbar 


e Calling a function ignoring its prototype. 


e Combined with goto, as a slightly weird function call that has the current call frame replaced with the caller. 
Think the linux exec() API call, but for functions. 
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Section 3.7: Hash References 


Hash references are scalars which contain a pointer to the memory location containing the data of a hash. Because 


the scalar points directly to the hash itself, when it is passed to a subroutine, changes made to the hash are not 
local to the subroutine as with a regular hash, but instead are global. 


First, let's examine what happens when you pass a normal hash to a subroutine and modify it within there: 


use strict; 
use warnings; 
use Data: :Dumper; 
sub modify 
my %hash = @_; 


Shash{new_value} = 2; 


print Dumper("Within the subroutine") ; 
print Dumper(\%hash) ; 


return; 


} 

my %example_hash = ( 
old_value => 1, 

Ne 


modify (%example_hash) ; 


print Dumper("After exiting the subroutine"); 
print Dumper(\%example_hash) ; 


Which results in: 


SVAR1 = ‘Within the subroutine’ ; 


SVAR1 = { 
'new_value' => 2, 
'old_value' => 1 
J; 
SVAR1 = 'After exiting the subroutine'; 
SVAR1 = { 
'old_value' => 1 
yy 


Notice that after we exit the subroutine, the hash remains unaltered; all changes to it were local to the modify 
subroutine, because we passed a copy of the hash, not the hash itself. 


In comparison, when you pass a hashref, you are passing the address to the original hash, so any changes made 
within the subroutine will be made to the original hash: 


use strict; 
use warnings; 
use Data: :Dumper; 


sub modify 


my Shashref = shift; 
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# De-reference the hash to add a new value 
Shashref->{new_value} = 2; 


print Dumper("Within the subroutine"); 
print Dumper(Shashref) ; 


return; 


} 
# Create a hashref 
my Sexample_ref = { 


old_value = Sele 


pe 


# Pass a hashref to a subroutine 
modify (Sexample_ref ) ; 


print Dumper("After exiting the subroutine"); 
print Dumper(Sexample_ref) ; 


This will result in: 


SVAR1 = ‘Within the subroutine’; 


SVAR1 = { 
'new_value' => 2, 
'old_value' => 1 
i 
SVAR1 = ‘After exiting the subroutine’ ; 
SVAR1 = { 
'new_value' => 2, 
"old_value' => 1 
i 


Section 3.8: Hashes 


Hashes can be understood as lookup-tables. You can access its contents by specifiying a key for each of them. Keys 
must be strings. If they're not, they will be converted to strings. 


If you give the hash simply a known key, it will serve you its value. 


# Elements are in (key, value, key, value) sequence 
my %inhabitants_of = ("London", 8674000, "Paris", 2244000); 


# You can save some typing and gain in clarity by using the "fat comma" 


# syntactical sugar. It behaves like a comma and quotes what's on the left. 
my %translations_of_hello = (spanish => 'Hola', german => 'Hallo', swedish => 'Hej'); 


In the following example, note the brackets and sigil: you access an element of %hash using Shash{key} because the 
value you want is a scalar. Some consider it good practice to quote the key while others find this style visually noisy. 
Quoting is only required for keys that could be mistaken for expressions like Shash{' some-key' } 


my S$greeting = S$translations_of_hello{' spanish’ }; 


While Perl by default will try to use barewords as strings, + modifier can also be used to indicate to Perl that key 
should not be interpolated but executed with result of execution being used as a key: 


my %employee = ( name => ‘John Doe', shift => ‘night’ ); 
# this example will print ‘night’ 
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print Semployee{shift}; 


# but this one will execute [shift][1], extracting first element from @_, 
# and use result as a key 
print Semployee{+shift}; 


Like with arrays, you can access multiple hash elements at the same time. This is called a hash slice. The resulting 
value is a list, so use the @ sigil: 


my @words = @translations_of_hello{'spanish', 'german'}; # ('Hola', ‘Hallo') 
Iterate over the keys of an hash with keys keys will return items in a random order. Combine with sort if you wish. 


for my Slang (sort keys %translations_of_hello) { 
say Stranslations_of_hello{Slang}; 
} 


If you do not actually need the keys like in the previous example, values returns the hash's values directly: 


for my Stranslation (values %translations_of_hello) { 
say Stranslation; 


} 


You can also use a while loop with each to iterate over the hash. This way, you will get both the key and the value at 
the same time, without a separate value lookup. Its use is however discouraged, as each can break in mistifying 


ways. 





# DISCOURAGED 
while (my ($lang, $translation) = each %translations_of_hello) { 
say Stranslation; 


} 
Access to unset elements returns undef, not an error: 
my $italian = $translations_of_hello{'italian'}; # undef 


map and list flattening can be used to create hashes out of arrays. This is a popular way to create a 'set' of values, 
e.g. to quickly check whether a value is in @elems. This operation usually takes O(n) time (i.e. proportional to the 
number of elements) but can be done in constant time (O(1)) by turning the list into a hash: 


@elems = qw(x y x z t); 

my %set = map { $_ => 1 } @elems; 2 (OG thy Nao Up iy W), 
my Sy_membership = Sset{'y'}; #1 

my Sw_membership = $set{'w'}; # undef 


This requires some explanation. The contents of @elems get read into a list, which is processed by map. map accepts a 
code block that gets called for each value of its input list; the value of the element is available for use in $_. Our 
code block returns two list elements for each input element: $_, the input element, and 1, just some value. Once you 
account for list flattening, the outcome is that map { $_ => 1 } @elems turns qw(x y x z t)into (x => 1, y => 
1, x => 1, z => 1, t => 1). 


As those elements get assigned into the hash, odd elements become hash keys and even elements become hash 
values. When a key is specified multiple times in a list to be assigned to a hash, the /ast value wins. This effectively 
discards duplicates. 
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A faster way to turn a list into a hash uses assignment to a hash slice. It uses the x operator to multiply the single- 
element list (1) by the size of @elems, so there is a 1 value for each of the keys in the slice on the left hand side: 


@elems = qw(x y x z t); 
my %set; 
@set{@elems} = (1) x @elems; 


The following application of hashes also exploits the fact that hashes and lists can often be used interchangeably to 
implement named function args: 


sub hash_args { 
my %args = @_; 
my %defaults = (foo => 1, bar => @); 
my %overrides = (__unsafe => ð); 
my %settings = (%defaults, %args, %overrides) ; 


} 


# This function can then be called like this: 

hash_args(foo => 5, bar => 3); # (foo => 5, bar => 3 
hash_args(); # (foo => 1, bar => @ 
hash_args(__unsafe => 1) # (foo => 1, bar => 6 


I as 


unsafe ==> @) 
unsafe ==> @) 
unsafe ==> @) 


PUSS 


hss 


When used as booleans, hashes are true if they are not empty. 
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Chapter 4: Interpolation in Perl 
Section 4.1: What is interpolated 


Perl interpolates variable names: 


my $name = ‘Paul'; 
print "Hello, Sname!\n"; # Hello, Paul! 


my @char = (‘a', 'b', 
print "Schar[1]\n"; # b 


eDi: 


my %map = (a => 125, b => 1080, c => 11); 
print "Smap{a}\n"; # 125 
Arrays may be interpolated as a whole, their elements are separated by spaces: 


my echar = (a. bo.) uei): 
print "My chars are @char\n"; # My chars are abc 


Perl does not interpolate hashes as a whole: 


my “map = (a => 125, b => 1080, c => 11); 
print "My map is %map\n"; # My map is %map 


and function calls (including constants): 


use constant { 
PI => '3.1415926' 


J; 
print "I like PI\n"; # I like PI 
print =T like i PI An A T like 31415926 


Perl interpolates escape sequences starting with \: 


\t horizontal tab 
\n newline 

\r return 

\f form feed 

\b backspace 

\a alarm (bell) 
\e escape 


Interpolation of \n depends on the system where program is working: it will produce a newline character(s) 
according to the current system conventions. 


Perl does not interpolate \v, which means vertical tab in C and other languages. 
Character may be addressed using their codes: 


\x{1d11e} 22??? by hexadecimal code 
\o0{350436} 22??? by octal code 
\N{U+1d11e}  ???? by Unicode code point 


or Unicode names: 
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\N{MUSICAL SYMBOL G CLEF} 
Character with codes from @x@@ to @xFF in the native encoding may be addressed in a shorter form: 


\x0a hexadecimal 
\012 octal 


Control character may be addressed using special escape sequences: 


\c@ chr(@) 

\ca chr(1) 

\cb chr(2) 

\cz chr(26) 

Nell chr(27) 

\c\ chr(28) # Cannot be used at the end of a string 
# since backslash will interpolate the terminating quote 

\cil chr(29) 

wer chr(30) 

Nese chr(31) 

NG? chnG@27) 


Il 
-_ 
O 
o 


Uppercase letters have the same meaning: "\cA" = 


Interpretation of all escape sequences except for \N{...} may depend on the platform since they use platform- 
and encoding-dependent codes. 


Section 4.2: Basic interpolation 


Interpolation means that Perl interpreter will substitute the values of variables for their name and some symbols 
(which are impossible or difficult to type in directly) for special sequences of characters (it is also known as 
escaping). The most important distinction is between single and double quotes: double quotes interpolate the 
enclosed string, but single quotes do not. 


my $name = ‘Paul'; 

my Sage = 64; 

print "My name is Sname.\nI am Sage.\n"; # My name is Paul. 
# I am 64. 

But: 


print 'My name is Sname.\nI am Sage.\n'; # My name is Sname.\nI am Sage.\n 


You can use q{} (with any delimiter) instead of single quotes and qq{} instead of double quotes. For example, 
q{I'm 64} allows to use an apostrophe within a non-interpolated string (otherwise it would terminate the string). 


Statements: 


print qq{Sname said: "I'm Sage".}; # Paul said: "I'm 64". 
print "$name said: \"I'm Sage\"." # Paul said: "I'm 64". 


do the same thing, but in the first one you do not need to escape double quotes within the string. 
If your variable name clashes with surrounding text, you can use the syntax ${var} to disambiguate: 


my Sdecade = 80; 
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print "I like ${decade}s music!" # I like 8@s music! 
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Chapter 5: True and false 


Section 5.1: List of true and false values 


use feature qw( say ); 


# Numbers are true if they're not equal to @. 


say 0 ? 'true' : 'false'; # false 
say 1 ? 'true' : 'false'; # true 
say 2 ? 'true' : 'false'; # true 
say -1 ? 'true' : 'false'; # true 
say 1-1 ? 'true' : 'false'; # false 
say 0e7 ? 'true' : 'false'; # false 
say -0.00 ? 'true' : 'false'; # false 
# Strings are true if they're not empty. 

say ‘a' ? 'true' : 'false'; # true 
say ‘false’ ? 'true' : 'false'; # true 
say mi ? 'true' : 'false'; # false 


# Even if a string would be treated as @ in numeric context, it's true if nonempty. 
# The only exception is the string "@", which is false. 
# To force numeric context add @ to the string 


say '0' ? 'true' : 'false'; # false 
say '0.0' ? 'true' : 'false'; # true 
say '0eQ' ? 'true' : 'false'; # true 
say '@ but true’ ? 'true' : 'false'; # true 
say '@ whargarbl' ? 'true' : 'false'; # true 
say 0+'@ argarbl' ? ‘true’ : 'false'; # false 


# Things that become numbers in scalar context are treated as numbers. 


my @c = (); 
my @d = (8); 
say @c ? 'true' : 'false'; # false 
say @d ? 'true' : 'false'; # true 


# Anything undefined is false. 
say undef ? 'true' : 'false'; # false 


# References are always true, even if they point at something false 


my @c = (); 
my $d = 9; 
say \@c ? 'true' : 'false'; # true 
say \Sd ? 'true' : 'false'; # true 
say \0 ? 'true' : '‘false'; # true 
say \'' ? 'true' : 'false'; # true 
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Chapter 6: Dates and Time 


Section 6.1: Date formatting 
Time::Piece is available in perl 5 after version 10 


use Time: :Piece; 


my $date = localtime->strftime( '%m/%d/%Y' ); 
print Sdate; 


Output 
07/26/2016 


Section 6.2: Create new DateTime 


Install DateTime on your PC and then use it in perl script: 

use DateTime; 

Create new current datetime 

dt = DateTime->now( time_zone => 'Asia/Ho_Chi_Minh' ); 


Then you can access elements's values of date and time: 


Syear = Sdt->year; 
$month = $dt->month; 
$day = $dt->day; 

hour = Sdt->hour; 


Sminute = Sdt->minute; 
Ssecond = Sdt->second; 


To get only time: 
my $time = Sdt->hms; #return time with format hh:mm:ss 
To get only date: 


my $date = Sdt->ymd; #return date with format yyyy-mm-dd 


Section 6.3: Working with elements of datetime 


Set single element: 

S$dt->set( year => 2016 ); 

Set many elements: 

Sdt->set( year => 2016, 'month' => 8); 
Add duration to datetime 

$dt->add( hour => 1, month => 2) 


Datetime subtraction: 
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my Sdt1 = DateTime->new( 


year => 2016, 
month => 8, 
day => 20, 

Ns 

my Sdt2 = DateTime->new( 
year => 2016, 
month => 8, 
day => 24, 


Me 


my $duration = $dt2->subtract_datetime(Sdt1) ; 
print S$duration->days 


You will get the result is 4 days 


Section 6.4: Calculate code execution time 


use Time: :HiRes qw( time ); 
my Sstart = time(); 


#Code for which execution time is calculated 
sleep(1.2); 


my Send = time(); 


printf("Execution Time: %@.02f s\n", Send - $start); 


This will print execution time of Code in seconds 
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Chapter 7: Control Statements 


Section 7.1: Conditionals 


Perl supports many kinds of conditional statements (statements that are based on boolean results). The most 
common conditional statements are if-else, unless, and ternary statements. given statements are introduced as a 
switch-like construct from C-derived languages and are available in versions Perl 5.10 and above. 


If-Else Statements 

The basic structure of an if-statement is like this: 
if 
i 


iif 
if 


EXPR) BLOCK 

EXPR) BLOCK else BLOCK 

EXPR) BLOCK elsif (EXPR) BLOCK ... 

EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK 


P 


For simple if-statements, the if can precede or succeed the code to be executed. 


$number = 7; 
if ($number > 4) { print "$number is greater than four!"; } 


# Can also be written this way 
print "$number is greater than four!" if $number > 4; 


Section 7.2: Loops 


Perl supports many kinds of loop constructs: for/foreach, while/do-while, and until. 


@numbers = 1..42; 
for (my $i=0; $i <= S#numbers; $i++) { 
print "Snumbers[$i]\n"; 


} 


#Can also be written as 
foreach my Snum (@numbers) { 
print "Snum\n"; 


} 


The while loop evaluates the conditional before executing the associated block. So, sometimes the block is never 
executed. For example, the following code would never be executed if the filehandle Sfh was the filehandle for an 
empty file, or if was already exhausted before the conditional. 


while (my $line = readline $fh) { 
say Sline; 


} 


The do/while and do/until loops, on the other hand, evaluate the conditional after each time the block is executed. 


So, a do/while or a do/until loop is always executed at least once. 


my Sgreeting_count = ð; 

do { 
say "Hello"; 
Sgreeting_count++; 

} until ( $greeting_count > 1) 
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# Hello 
# Hello 
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Chapter 8: Subroutines 


Section 8.1: Creating subroutines 
Subroutines are created by using the keyword sub followed by an identifier and a code block enclosed in braces. 


You can access the arguments by using the special variable @_, which contains all arguments as an array. 


sub function_name { 
my (Sargl1, Sarg2, @more_args) = @_; 
Oe fea 


Since the function shift defaults to shifting @_ when used inside a subroutine, it's a common pattern to extract the 
arguments sequentially into local variables at the beginning of a subroutine: 


sub function_name { 
my Sarg1 = shift; 
my Sarg2 = shift; 
my @more_args = @_; 
#... 

} 


# emulate named parameters (instead of positional) 
sub function_name { 
my “args = (arg1 => ‘default', @_); 
my Sarg1 = delete Sargs{arg1}; 
my Sarg2 = delete Sargs{arg2}; 
R 
} 
sub { 
my Sarg1 = shift; 
# oan 
}->(Sarg) ; 
Version = 5.20.0 


Alternatively, the experimental feature "signatures" can be used to unpack parameters, which are passed by value 
(not by reference). 


use feature "signatures"; 
sub function_name(Sarg1, Sarg2, @more_args) { 


ae 
} 


Default values can be used for the parameters. 


use feature "signatures"; 


sub function_name($arg1=1, Sarg2=2) { 
H 
} 


You can use any expression to give a default value to a parameter — including other parameters. 
sub function_name(Sargi=1, Sarg2=Sarg1+1) { 
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Note that you can't reference parameters which are defined after the current parameter — hence the following code 
doesn't work quite as expected. 


sub function_name(Sarg1=Sarg2, Sarg2=1) { 
print Sargi: # => <nothing> 
print, $arg2; # == 1 


Section 8.2: Subroutines 


Subroutines hold code. Unless specified otherwise, they are globally defined. 


# Functions do not (have to) specify their argument list 

sub returns_one { 
# Functions return the value of the last expression by default 
# The return keyword here is unnecessary, but helps readability. 


return 1; 
} 
# Its arguments are available in @_, however 
sub sum { 

my $ret = ð; 


for my $value (@_) { 
$ret += $value 

} 

return $ret; 


} 


# Perl makes an effort to make parens around argument list optional 
say sum 1..3; #6 


# If you treat functions as variables, the & sigil is mandatory. 
say defined &sum; # 1 


Some builtins such as print or say are keywords, not functions, so e.g. &say is undefined. It also does mean that 
you can define them, but you will have to specify the package name to actually call them 


# This defines the function under the default package, 'main' 
sub say { 
# This is instead the say keyword 


say "I say, @_"; 
} 


# ...so you can call it like this: 
main: :say('wow'); # I say, wow. 


Version = 5.18.0 


Since Perl 5.18, you can also have non-global functions: 


use feature 'lexical_subs'; 
my Svalue; 
{ 
# Nasty code ahead 
my sub prod { 
my Sret = 1; 
$ret *= $_ for @; 
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Sret; 
} 
$value = prod 1..6; # 720 
say defined &prod; # 7 


} 
say defined &prod; # @ 


Version = 5.20.0 


Since 5.20, you can also have named parameters. 


use feature ‘signatures’; 
sub greet(Sname) { 
say "Hello, Sname"; 


} 


This should not be confused with prototypes, a facility Perl has to let you define functions that behave like built-ins. 
Function prototypes must be visible at compile time and its effects can be ignored by specifying the & sigil. 
Prototypes are generally considered to be an advanced feature that is best used with great care. 


# This prototype makes it a compilation error to call this function with anything 
# that isn't an array. Additionally, arrays are automatically turned into arrayrefs 
sub receives_arrayrefs(\@\@) { 

my $x = shift; 

my Sy = shift; 
} 


my @a = (1..3); 

my eB = (1.24): 

receives_arrayrefs(@a, @b); # okay, Sx = \@a, Sy = \@b, @ = (); 
receives_arrayrefs(\@a, \@b); # compilation error, "Type ... must be array ..." 
BEGIN { receives_arrayrefs(\@a, \@b); } 


# Specify the sigil to ignore the prototypes. 
&receives_arrayrefs(\@a, \@b); # okay, Sx = \@a, Sy = \@b, @ = (); 
&receives_arrayrefs(@a, @b); Hok but SX =i, Sy S2 om 2 aA) 


Section 8.3: Subroutine arguments are passed by reference 
(except those in signatures) 


Subroutine arguments in Perl are passed by reference, unless they are in the signature. This means that the 
members of the @_ array inside the sub are just aliases to the actual arguments. In the following example, $text in 
the main program is left modified after the subroutine call because $_[0] inside the sub is actually just a different 
name for the same variable. The second invocation throws an error because a string literal is not a variable and 
therefore can't be modified. 


use feature 'say'; 


sub edit { 
Sio] =~ s/world/sub/; 
} 
my Stext = "Hello, world!"; 
edit ($text) ; 
say Stext; # Hello, sub! 


edit("Hello, world!"); # Error: Modification of a read-only value attempted 


To avoid clobbering your caller's variables it is therefore important to copy @_ to locally scoped variables (my ...) as 
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described under "Creating subroutines". 
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Chapter 9: Debug Output 


Section 9.1: Dumping with Style 


Sometimes Data::Dumper is not enough. Got a Moose object you want to inspect? Huge numbers of the same 
structure? Want stuff sorted? Colored? Data::Printer is your friend. 


use Data: :Printer; 


p Sdata_structure; 


Data::Printer writes to STDERR, like warn. That makes it easier to find the output. By default, it sorts hash keys and 
looks at objects. 


use Data: :Printer; 
use LWP: :UserAgent; 


my Sua = LWP: :UserAgent->new; 
p Sua; 


It will look at all the methods of the object, and also list the internals. 


LWP::UserAgent { 

Parents LWP: :MemberMixin 

public methods (45) : add_handler, agent, clone, conn_cache, cookie_jar, credentials, 
default_header, default_headers, delete, env_proxy, from, get, get_basic_credentials, 
get_my_handler, handlers, head, is_online, is_protocol_supported, local_address, max_redirect, 
max_size, mirror, new, no_proxy, parse_head, post, prepare_request, progress, protocols_allowed, 
protocols_forbidden, proxy, put, redirect_ok, remove_handler, request, requests_redirectable, 
run_handlers, send_request, set_my_handler, show_progress, simple_request, ssl_opts, timeout, 
use_alarm, use_eval 


private methods (4) : _agent, _need_proxy, _new_response, _process_colonic_headers 
internals: { 
def_headers HTTP: :Headers, 
handlers { 
response_header HTTP: :Config 
i 
local_address undef, 
max_redirect Ths 
max_size undef, 
no_proxy Ie 
protocols_allowed undef , 
protocols_forbidden undef, 
proxy {E 
requests_redirectable [ 
[0] "GET", 
[1] HEADY 
l 
show_progress undef, 
ssl_opts { 
verify_hostname 1 
y 
timeout 180, 
use_eval 1 
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You can configure it further, so it serializes certain objects in a certain way, or to include objects up to an arbitrary 
depth. The full configuration is available in the documentation. 





Unfortunately Data::Printer does not ship with Perl, so you need to install it from CPAN or through your package 
management system. 





Section 9.2: Dumping data-structures 


use Data: :Dumper; 


my Sdata_structure = { foo => ‘bar’ }; 
print Dumper Sdata_structure; 


Using Data::Dumper is an easy way to look at data structures or variable content at run time. It ships with Perl and 
you can load it easily. The Dumper function returns the data structure serialized in a way that looks like Perl code. 


SVAR1 = { 


} 


That makes it very useful to quickly look at some values in your code. It's one of the most handy tools you have in 
your arsenal. Read the full documentation on metacpan. 


Section 9.3: Data::Show 


The function show is automatically exported when use Data: :Show; is executed. This function takes a variable as its 
sole argument and it outputs: 


. the name of the variable 

. the contents of that variable (in a readable format) 
. the line of the file that show is run from 

. the file show is run from 


AUN > 


Assuming that the following is code from the file example. p1: 


use strict; 

use warnings; 

use Data: :Show; 

my @array =a 2 23 A S 67 8 9 Toe 

my %hash = ( foo => 1, bar => { baz => 10, qux => 20 } ); 
my $href = \%hash; 

show @array; 


show %hash; 
show $href; 


perl example .p1 gives the following output: 


======( @array ecl 'example.pl' i line 11 lss s55 
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======( %hash Jeee 'example.pl', line 12 |es= 


{ bar => { baz => 10, qux => 20 }, foo => 1 } 


======( Shref \ESeSS= 2656S SF 6 || ‘example.p1' i line 13 |2252 


{ bar => { baz => 10, qux => 20 }, foo => 1 } 


See the documentation for Data: : Show. 





Section 9.4: Dumping array list 


my @data_array = (123, 456, 789, 'poi', ‘uyt', "rew", "qas"); 
print Dumper @data_array; 


Using Data::Dumper gives an easy access to fetch list values. The Dumper returns the list values serialized in a way 
that looks like Perl code. 


Output: 

SVAR1 = 123; 
SVAR2 = 456; 
SVAR3 = 789; 
SVAR4 = 'poi'; 
SVAR5 = ‘uyt'; 
SVAR6 = ‘rew'; 
SVAR7 = gasi: 


As suggested by user @dgw When dumping arrays or hashes it is better to use an array reference or a hash 
reference, those will be shown better fitting to the input. 


Sref_data = [23,45,67,'mnb','vcx']; 
print Dumper Sref_data; 


Output: 

SVAR1 = [ 
23, 
45, 
67, 
'mnb', 
NOX 


lE 
You can also reference the array when printing. 


my @data_array = (23,45,67, 'mnb’, 'vcx'); 
print Dumper \@data_array; 


Output: 


SVAR1 = [ 
23, 
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Chapter 10: Lists 


Section 10.1: Array as list 


The array is one of Perl's basic variable types. It contains a list, which is an ordered sequence of zero or more 
scalars. The array is the variable holding (and providing access to) the list data, as is documented in perldata. 


You can assign a list to an array: 
my @foo = ( 4, 5, 6 ); 
You can use an array wherever a list is expected: 


join nao ( 4, 5, 6 Ne 
join '-', @foo; 


Some operators only work with arrays since they mutate the list an array contains: 


shift @array; 

únshifte @array CI 2 seni 
pop @array; 

push @array, ( 7, 8, 9 ); 


Section 10.2: Assigning a list to a hash 


Lists can also be assigned to hash variables. When creating a list that will be assigned to a hash variable, it is 
recommended to use the fat comma => between keys and values to show their relationship: 


my %hash = ( foo => 42, bar => 43, baz => 44 ); 


The => is really only a special comma that automatically quotes the operand to its left. So, you could use normal 
commas, but the relationship is not as clear: 


my shash = ( foon 42, ‘bar’, 43, ‘baz', 44 ); 


You can also use quoted strings for the left hand operand of the fat comma =>, which is especially useful for keys 
containing spaces. 


my sash = ( feo bar => 42, baz qux. => 48 ); 


For details see Comma operator at perldoc perlop. 





Section 10.3: Lists can be passed into subroutines 


As to pass list into a subroutine, you specify the subroutine's name and then supply the list to it: 


test_subroutine( ‘item1', ‘item2' ); 
test_subroutine ‘item1', ‘item2'; # same 


Internally Perl makes aliases to those arguments and put them into the array @_ which is available within the 
subroutine: 
@_ = ( ‘item1', ‘item2' ); # Done internally by perl 
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You access subroutine arguments like this: 


sub test_subroutine { 
print $_[0]; # item? 
print $_[1]; # item2 


Aliasing gives you the ability to change the original value of argument passed to subroutine: 


sub test_subroutine { 
s_[6] += 2; 
} 


my Sx = We 
test_subroutine( Sx ); 
print $x; # 9 


To prevent inadvertent changes of original values passed into your subroutine, you should copy them: 


sub test_subroutine { 
my( S$copy_arg1, Scopy_arg2 ) = @_; 
Scopy_arg1 += 2; 

} 


my $x = 7; 


test_subroutine $x; # in this case Scopy_arg2 will have ‘undef* value 
print Sx; #7 


To test how many arguments were passed into the subroutine, check the size of @_ 


sub test_subroutine { 
print scalar @_, ' argument(s) passed into subroutine’ ; 


} 


If you pass array arguments into a subroutine they all will be flattened: 


m axo 2 

my @y = qw/abe/: #( a, br, ce ) 

test_some_subroutine @x, 'hi', @y; # 7 argument(s) passed into subroutine 
#0 = (1 2:3, hi ai, bi ici ) # Done internally for this call 


If your test_some_subroutine contains the statement $_[4] = 'd', for the above call it will cause $y[9] to have 
value d afterwards: 


print "@y"; #dbc 


Section 10.4: Return list from subroutine 
You can, of course, return lists from subs: 


sub foo { 
my @list1 = ( 


teen S) 
my @list2 = ( 4, 5 


Ne 


return ( @list1, @list2 ); 
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my @list = foo(); 
print @list; # 12345 


But it is not the recommended way to do that unless you know what you are doing. 


While this is OK when the result is in LIST context, in SCALAR context things are unclear. Let's take a look at the 
next line: 


print scalar foo(); #2 
Why 2? What is going on? 


1. Because foo() evaluated in SCALAR context, this list ( @list1, @list2 ) also evaluated in SCALAR context 
2. In SCALAR context, LIST returns its last element. Here it is @list2 
3. Again in SCALAR context, array @list2 returns the number of its elements. Here it is 2. 


In most cases the right strategy will return references to data structures. 
So in our case we should do the following instead: 


return ( \@list1, \@list2 ); 
Then the caller does something like this to receive the two returned arrayrefs: 


my (Slistl, Slist2) = fool ...); 


Section 10.5: Hash as list 
In list context hash is flattened. 
my @bar = ( %hash, %hash ); 


The array @bar is initialized by list of two %hash hashes 


e both %hash are flattened 
e new list is created from flattened items 
e @bar array is initialized by that list 


It is guaranteed that key-value pairs goes together. Keys are always even indexed, values - odd. It is not guaranteed 
that key-value pairs are always flattened in same order: 


my %hash = ( a => 1, b => 2 ); 
print %hash; # Maybe 'a1b2' or 'b2al1' 


Section 10.6: Using arrayref to pass array to sub 


The arrayref for @foo is \@foo. This is handy if you need to pass an array and other things to a subroutine. Passing 
@foo is like passing multiple scalars. But passing \@foo is a single scalar. Inside the subroutine: 


xyz(\@foo, 123); 
sub xyz { 
my (Sarr, Setc) = @_; 
print Sarr->[0]; # using the first item in Sarr. It is like Sfoo[@] 
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Chapter 11: Sorting 


For sorting lists of things, Perl has only a single function, unsurprisingly called sort. It is flexible enough to sort all 
kinds of items: numbers, strings in any number of encodings, nested data structures or objects. However, due to its 
flexibility, there are quite a few tricks and idioms to be learned for its use. 


Section 11.1: Basic Lexical Sort 


@sorted = sort @list; 
@sorted = sort { Sa cmp Sb } @list; 


sub compare { $a cmp Sb } 
@sorted = sort compare @list; 


The three examples above do exactly the same thing. If you don't supply any comparator function or block, sort 
assumes you want the list on its right sorted lexically. This is usually the form you want if you just need your data in 
some predictable order and don't care about linguistic correctness. 


sort passes pairs of items in @list to the comparator function, which tells sort which item is larger. The cmp 
operator does this for strings while <=> does the same thing for numbers. The comparator is called quite often, on 
average n* log(n) times with n being the number of elements to be sorted, so it's important it be fast. This is the 
reason sort uses predefined package global variables ($a and $b) to pass the elements to be compared to the block 
or function, instead of proper function parameters. 


If you use locale, cmp takes locale specific collation order into account, e.g. it will sort A like A under a Danish locale 
but after Z under an English or German one. However, it doesn't take the more complex Unicode sorting rules into 
account nor does it offer any control over the order—for example phone books are often sorted differently from 
dictionaries. For those cases, the Unicode: :Collate and particularly Unicode: :Collate: :Locale modules are 
recommended. 


Section 11.2: The Schwartzian Transform 


This is probably the most famous example of a sort optimization making use of Perl's functional programming 
facilities, to be used where the sort order of items depend on an expensive function. 


# What you would usually do 
@sorted = sort { slow(Sa) <=> slow(Sb) } @list; 


# What you do to make it faster 
@sorted = 

map { $_->[8] } 

sort { Sa->[1] <=> $b->[1] } 
map { [ $_, slow($_) ] } 
@list; 


The trouble with the first example is that the comparator is called very often and keeps recalculating values using a 
slow function over and over. A typical example would be sorting file names by their file size: 


use File: :stat; 
@sorted = sort { stat($a)->size <=> stat($b)->size } glob "x"; 


This works, but at best it incurs the overhead of two system calls per comparison, at worst it has to go to the disk, 
twice, for every single comparison, and that disk may be in an overloaded file server on the other side of the planet. 
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Enter Randall Schwartz's trick. 


The Schwartzian Transform basically shoves @list through three functions, bottom-to-top. The first map turns each 
entry into a two-element list of the original item and the result of the slow function as a sort key, so at the end of 
this we have called slow() exactly once for each element. The following sort can then simply access the sort key by 
looking in the list. As we don't care about the sort keys but only need the original elements in sorted order, the final 
map throws away the two-element lists from the already-sorted list it receives from @sort and returns a list of only 
their first members. 


Section 11.3: Case Insensitive Sort 
The traditional technique to make sort ignore case is to pass strings to 1c or uc for comparison: 
@sorted = sort { lc($a) cmp lc($b) } @list; 


This works on all versions of Perl 5 and is completely sufficient for English; it doesn't matter whether you use uc or 
lc. However, it presents a problem for languages like Greek or Turkish where there is no 1:1 correspondence 
between upper- and lowercase letters so you get different results depending on whether you use uc or lc. 
Therefore, Perl 5.16 and higher have a case folding function called fc that avoids this problem, so modern multi- 
lingual sorting should use this: 


@sorted = sort { fc(Sa) cmp fc($b) } @list; 


Section 11.4: Numeric Sort 


@sorted = sort { Sa <=> Sb } @list; 


Comparing $a and $b with the <=> operator ensures they are compared numerically and not textually as per 
default. 


Section 11.5: Reverse Sort 


@sorted = sort { Sb <=> Sa } @list; 
@sorted = reverse sort { Sa <=> Sb } @list; 


Sorting items in descending order can simply be achieved by swapping $a and $b in the comparator block. 
However, some people prefer the clarity of a separate reverse even though it is slightly slower. 
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Chapter 12: File I/O (reading and writing 
files) 


Mode Explaination 
> Write (trunc). Will overwrite existing files. Creates a new file if no file was found 


., Write (append). Will not overwrite files but append new content at the end of it. Will also create a file if used 
for opening a non existing file. 

< Read. Opens the file in read only mode. 

+< Read / Write. Will not create or truncate the file. 

+> Read / Write (trunc). Will create and truncate the file. 


+>> Read / Write (append). Will create but not truncate the file. 


Section 12.1: Opening A FileHandle for Reading 


Opening Generic ASCII Text Files 
Version = 5.6.0 


open my Sfilehandle, '<', Sname_of_file or die "Can't open Sname_of_file, $!"; 


This is the basic idiom for "default" File IO and makes $filehandle a readable input stream of bytes, filtered by a 
default system-specific decoder, which can be locally set with the open pragma 


Perl itself does not handle errors in file opening, so you have to handle those yourself by checking the exit condition 
of open. $! is populated with the error message that caused open to fail. 


On Windows, the default decoder is a "CRLF" filter, which maps any "\r\n" sequences in the input to "\n" 


Opening Binary Files 
Version = 5.8.0 


open my Sfilehandle, ‘<:raw', ‘path/to/file' or die "Can't open Sname_of_file, $!"; 


This specifies that Perl should not perform a CRLF translation on Windows. 


Opening UTF8 Text Files 
Version = 5.8.0 


open my Sfilehandle, '<:raw:encoding(utf-8)', ‘path/to/file' 
or die "Can't open Sname_of_file, $!"; 


This specifies that Perl should both avoid CRLF translation, and then decode the resulting bytes into strings of 
characters ( internally implemented as arrays of integers which can exceed 255 ), instead of strings of bytes 


Section 12.2: Reading from a file 


my $filename = '/path/to/file' ; 


open my Sfh, '<', $filename or die “Failed to open file: $filename"; 
# You can then either read the file one line at a time... 
while(chomp(my $line = <Sfh>)) { 

print $line . "\n"; 


} 


# ...or read whole file into an array in one go 
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chomp(my @fileArray = <Sfh>); 

If you know that your input file is UTF-8, you can specify the encoding: 

open my Sfh, '<:encoding(utf8)', $filename or die "Failed to open file: $filename"; 
After finished reading from the file, the filehandle should be closed: 

close $fh or warn "close failed: $!"; 


See also: Reading a file into a variable 


Another and faster way to read a file is to use File::Slurper Module. This is useful if you work with many files. 


use File: :Slurper; 
my $file = read_text("path/to/file"); # utf8 without CRLF transforms by default 
print $file; #Contains the file body 


See also: [Reading a file with slurp] 


Section 12.3: Write to a file 


This code opens a file for writing. Returns an error if the file couldn't be opened. Also closes the file at the end. 





#!/usr/bin/perl 

use strict; 

use warnings; 

use open qw( :encoding(UTF-8) :std ); # Make UTF-8 default encoding 


# Open "output.txt" for writing (">") and from now on, refer to it as the variable Sfh. 


open(my Sfh, ">", "“output.txt") 
# In case the action failed, print error message and quit. 
or die "Can't open > output.txt: $!"; 


Now we have an open file ready for writing which we access through Sfh (this variable is called a filehandle). Next 
we can direct output to that file using the print operator: 


# Print "Hello" to Sfh ("output.txt"). 

print S$fh "Hello"; 

# Don't forget to close the file once we're done! 
close Sfh or warn "Close failed: $!"; 


The open operator has a scalar variable ($fh in this case) as its first parameter. Since it is defined in the open 
operator it is treated as a filehandle. Second parameter ">" (greater than) defines that the file is opened for writing. 
The last parameter is the path of the file to write the data to. 


To write the data into the file, the print operator is used along with the fi/ehandle. Notice that in the print operator 
there is no comma between the filehandle and the statement itself, just whitespace. 


Section 12.4: "use autodie” and you won't need to check file 
open/close failures 


autodie allows you to work with files without having to explicitly check for open/close failures. 


Since Perl 5.10.1, the autodie pragma has been available in core Perl. When used, Perl will automatically check for 
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errors when opening and closing files. 


Here is an example in which all of the lines of one file are read and then written to the end of a log file. 


use 5.010; # 5.010 and later enable "say", which prints arguments, then a newline 
use strict; # require declaring variables (avoid silent errors due to typos) 

use warnings; # enable helpful syntax-related warnings 

use open qw( :encoding(UTF-8) :std ); # Make UTF-8 default encoding 

use autodie; # Automatically handle errors in opening and closing files 


open(my Sfh_in, ‘<', “input.txt"); # check for failure is automatic 


# open a file for appending (i.e. using ">>" 


open( my S$fh_log, '>>', “output.log"); # check for failure is automatic 
while (my $line = readline $fh_in) # also works: while (my $line = <Sfh_in>) 
{ 


# remove newline 
chomp Sline; 


# write to log file 
say $fh_log $line or die "failed to print '$line'"; # autodie doesn't check print 


} 


# Close the file handles (check for failure is automatic) 
close $fh_in; 
close $fh_log; 


By the way, you should technically always check print statements. Many people don't, but per1 (the Perl 
interpreter) doesn't do this automatically and neither does autodie. 





Section 12.5: Rewind a filehandle 
Sometimes it is needful to backtrack after reading. 


# identify current position in file, in case the first line isn't a comment 
my Scurrent_pos = tell; 


while (my $line = readline $fh) 


{ 
if ($line =~ /$START_OF_COMMENT_LINE/) 
{ 
push @names, get_name_from_comment(Sline) ; 
} 
else { 
last; # break out of the while loop 
} 


Scurrent_pos = tell; # keep track of current position, in case we need to rewind the next line 
read 


} 


# Step back a line so that it can be processed later as the first data line 
seek Sfh, Scurrent_pos, ð; 


Section 12.6: Reading and Writing gzip compressed files 
Writing a gzipped file 
To write a gzipped file, use the module I0: :Compress: :Gzip and create a filehandle by creating a new instance of 
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I0::Compress: :Gzip for the desired output file: 


use strict; 

use warnings; 

use open qw( :encoding(UTF-8) :std ); # Make UTF-8 default encoding 
use I0::Compress: :Gzip; 

my Sfh_out = I0::Compress: :Gzip->new("hello.txt.gz"); 

print Sfh_out "Hello World!\n"; 


close Sfh_out; 


use I0::Compress: :Gzip; 


Reading from a gzipped file 


To read from a gzipped file, use the module I0: :Uncompress: :Gunzip and then create a filehandle by creating a 
new instance of I0: :Uncompress: :Gunzip for the input file: 


#!/bin/env perl 

use strict; 

use warnings; 

use open qw( :encoding(UTF-8) :std ); # Make UTF-8 default encoding 
use I0::Uncompress: :Gunzip; 

my Sfh_in = IO: :Uncompress: :Gunzip->new("hello.txt.gz") ; 


my $line = readline $fh_in; 


print $line; 


Section 12.7: Setting the default Encoding for IO 


# encode/decode UTF-8 for files and standard input/output 
use open qw( :encoding(UTF-8) :std ); 


This pragma changes the default mode of reading and writing text ( files, standard input, standard output, and 
standard error ) to UTF-8, which is typically what you want when writing new applications. 


ASCII is a subset of UTF-8, so this is not expected to cause any problems with legacy ASCII files and will help protect 
you the accidental file corruption that can happen when treating UTF-8 files as ASCII. 


However, it is important that you know what the encoding of your files is that you are dealing with and handle them 
accordingly. (Reasons that we should not ignore Unicode.) For more in depth treatment of Unicode, please see the 
Perl Unicode topic. 
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Chapter 13: Reading a file's content into a 
variable 


Section 13.1: Path::Tiny 


Using the idiom from The Manual Way several times in a script soon gets tedious so you might want to try a 
module. 


use Path: :Tiny; 
my Scontents = path($filename)->slurp; 


You can pass a binmode option if you need control over file encodings, line endings etc. - see man perlio: 
my Scontents = path(Sfilename)->slurp( {binmode => ":encoding(UTF-8)"} ); 


Path: : Tiny also has a lot of other functions for dealing with files so it may be a good choice. 





Section 13.2: The manual way 


open my Sfh, '<', $filename 
or die "Could not open $filename for reading: $!"; 
my Scontents = do { local $/; <Sfh> }; 


After opening the file (read man perlio if you want to read specific file encodings instead of raw bytes), the trick is 
in the do block: <$fh>, the file handle in a diamond operator, returns a single record from the file. The "input record 
separator" variable $/ specifies what a "record" is—by default it is set to a newline character so "a record" means "a 
single line". As $/ is a global variable, local does two things: it creates a temporary local copy of $/ that will vanish 
at the end of the block, and gives it the (non-)value undef (the "value" which Perl gives to uninitialized variables). 
When the input record separator has that (non-)value, the diamond operator will return the entire file. (It considers 
the entire file to be a single line.) 


Using do, you can even get around manually opening a file. For repeated reading of files, 


sub readfile { do { local(@ARGV,$/) = $_[90]; <> } } 
my $content = readfile(S$filename) ; 


can be used. Here, another global variable(@ARGV) is localized to simulate the same process used when starting a 
perl script with parameters. $/ is still undef, since the array in front of it "eats" all incoming arguments. Next, the 
diamond operator <> again delivers one record defined by $/ (the whole file) and returns from the do block, which 
in turn return from the sub. 


The sub has no explicit error handling, which is bad practice! If an error occurs while reading the file, you will 
receive undef as return value, as opposed to an empty string from an empty file. 


Another disadvantage of the last code is the fact that you cannot use PerllO for different file encodings—you always 
get raw bytes. 


Section 13.3: File::Slurp 


Don't use it. Although it has been around for a long time and is still the module most programmers will suggest, it is 
broken and not likely to be fixed. 
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Section 13.4: File::Slurper 


This is a minimalist module that only slurps files into variables, nothing else. 


use File::Slurper ‘read_text'; 
my Scontents = read_text(Sfilename) ; 


read_text() takes two optional parameters to specify the file encoding and whether line endings should be 
translated between the unixish LF or DOSish CRLF standards: 


my Scontents = read_text(Sfilename, 'UTF-8', 1); 


Section 13.5: Slurping a file into an array variable 


open(my Sfh, '<', "/some/path") or die $!; 
my @ary = <Sfh>; 


When evaluated in list context, the diamond operator returns a list consisting of all the lines in the file (in this case, 
assigning the result to an array supplies list context). The line terminator is retained, and can be removed by 
chomping: 


chomp(@ary); #removes line terminators from all the array elements. 


Section 13.6: Slurp file in one-liner 


Input record separator can be specified with -@ switch (zero, not capital O). It takes an octal or hexadecimal number 
as value. Any value 0409 or above will cause Perl to slurp files, but by convention, the value used for this purpose is 
0777. 


perl -0777 -e ‘my $file = <>; print length(Sfile)' input.txt 


Going further with minimalism, specifying -n switch causes Perl to automatically read each line (in our case — the 
whole file) into variable $_. 


perl -0777 -ne ‘print length(S$_)' input.txt 
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Chapter 14: Strings and quoting methods 
Section 14.1: String Literal Quoting 


String literals imply no escaping or interpolation ( with the exception of quoting string terminators ) 
print 'This is a string literal\n'; # emits a literal \ and n to terminal 

print 'This literal contains a \'postraphe '; # emits the ' but not its preceding \ 
You can use alternative quoting mechanisms to avoid clashes: 


print q/This is is a literal \' <-- 2 characters /; # prints both \ and ' 
print q*This is is a literal \' <-- 2 characters ^; # also 


Certain chosen quote characters are "balanced" 


print q{ This is a literal and I contain { parens! } }; # prints inner { } 


Section 14.2: Double-quoting 


Double-quoted strings use interpolation and escaping — unlike single-quoted strings. To double-quote a string, 
use either double quotes " or the qq operator. 


my Sgreeting = "Hello!\n"; 

print Sgreeting; 

# => Hello! (followed by a linefeed) 

my Sbush = "They misunderestimated me." 


print qq/As Bush once said: "Sbush"\n/; 
# => As Bush once said: "They misunderestimated me." (with linefeed) 


The qq is useful here, to avoid having to escape the quotation marks. Without it, we would have to write... 
print "As Bush once said: \"Sbush\"\n"; 

... which just isn't as nice. 

Perl doesn't limit you to using a slash / with qq; you can use any (visible) character. 


use feature ‘say’; 
say qq/You can use slashes.../; 


say qq{...or braces...}; 
say qq*...or hats...*; 


say qq|...or pipes...|; 
# say qq ...but not whitespace. ; 


You can also interpolate arrays into strings. 


use feature ‘say'; 


my @letters = ('a', 'b', 'c'); 
say "I like these letters: @letters."; 
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# => I like these letters: abc. 


By default the values are space-separated — because the special variable $" defaults to a single space. This can, of 
course, be changed. 


use feature ‘say’; 


my @letters = ('a', 'b', ‘c'); 
{local $" = ", "; say "@letters"; } Hab b, C 


If you prefer, you have the option to use English and change $LIST_SEPARATOR instead: 


use v5.18; # English should be avoided on older Perls 
use English; 


my @letters = ('a', 'b', 'c'); 
{ local SLIST_SEPARATOR = "\n"; say "My favourite letters:\n\n@letters" } 


For anything more complex than this, you should use a loop instead. 


say "My favourite letters:"; 


say; 

for my Sletter (@letters) { 
say " - Sletter"; 

} 


Interpolation does not work with hashes. 


use feature ‘say’; 


my “hash = (ar, “<b; <07, d3): 
say "This doesn't work: %hash" # This doesn't work: %hash 


Some code abuses interpolation of references — avoid it. 


use feature ‘say’; 


say u2 k 2 == eee e; #2 +2 = 4 (avoid this) 
say “2 + 2 == SANE 2+2 yee #2 + 2 = 4 (avoid this) 
The so-called "cart operator" causes perl to dereference @{ ... } the array reference [ ... ] that contains the 


expression that you want to interpolate, 2 + 2. When you use this trick, Perl builds an anonymous array, then 
dereferences it and discards it. 


The ${\( ... )} version is somewhat less wasteful, but it still requires allocating memory and it is even harder to 
read. 


Instead, consider writing: 


© Say e2 pel == ee tee 
e my $result = 2 + 2; say "2 + 2 == Sresult" 


Section 14.3: Heredocs 


Large Multi-Line strings are burdensome to write. 
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my Svariable = <<'EOF’; 

this block of text is interpreted literally, 
no \'quotes matter, they're just text 

only the trailing left-aligned EOF matters. 
EOF 


NB: Make sure you ignore stack-overflows syntax highlighter: It is very wrong. 


And Interpolated Heredocs work the same way. 


my Svariable = <<"I Want it to End"; 

this block of text is interpreted. 

quotes\nare interpreted, and Sinterpolations 

get interpolated... 

but still, left-aligned "I Want it to End" matters. 
I Want it to End 


Pending in 5.26.0* is an "Indented Heredoc" Syntax which trims left-padding off for you 


Version = 5.26.0 
my variable = <<~"MuchNicer" ; 

this block of text is interpreted. 

quotes\nare interpreted, and Sinterpolations 

get interpolated... 

but still, left-aligned "I Want it to End" matters. 
MuchNicer 


Section 14.4: Removing trailing newlines 


The function chomp will remove one newline character, if present, from each scalar passed to it. chomp will mutate 
the original string and will return the number of characters removed 


my $str = “Hello World\n\n"; 

my Sremoved = chomp(Sstr) ; 

print $etr; # "Hello World\n" 
print $removed; # 1 


# chomp again, removing another newline 
removed = chomp $str; 

print Sstr; # "Hello World" 

print Sremoved; # 1 

# chomp again, but no newline to remove 
removed = chomp S$str; 


print Sstr; # "Hello World" 
print Sremoved; # @ 


You can also chomp more than one string at once: 


my @strs = ("Hello\n", "World!\n\n"); # one newline in first string, two in second 


my Sremoved = chomp(@strs); # @strs is now ("Hello", "“World!\n") 
print Sremoved; #2 


removed = chomp(@strs); # @strs is now ("Hello", "World!") 
print Sremoved; #1 


removed = chomp(@strs); # @strs is still ("Hello", "World!") 
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print Sremoved; #0 


But usually, no one worries about how many newlines were removed, so chomp is usually seen in void context, and 


usually due to having read lines from a file: 


while (my $line = readline $fh) 
{ 


chomp $line; 


# now do something with $line 


} 


my @lines = readline $fh2; 


chomp (@lines); # remove newline from end of each line 
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Chapter 15: Split a string on unquoted 
separators 


Section 15.1: parse_lineQ 


Using parse_line() of Text::ParseWords: 





use 5.010; 
use Text: :ParseWords; 


my $line = q{"a quoted, comma", word1, word2}; 
my @parsed = parse_line(',', 1, Sline); 
say for @parsed; 


Output: 


"a quoted, comma" 
word 


word2 


Section 15.2: Text::CSV or Text::CSV_XS 


use Text::CSV; # Can use Text::CSV which will switch to _XS if installed 


Sseplohar = u: 

my Scsv = Text: :CSV->new({sep_char => Ssep_char}); 
my $line = q{"a quoted, comma", word1, word2}; 
Scsv->parse(Sline) ; 

my @fields = Scsv->fields() ; 

print join("\n", @fields)."\n"; 


Output: 


a quoted, comma 
word 
word2 


NOTES 


e By default, Text::CSV does not strip whitespace around separator character, the way Text : :ParseWords does. 
However, adding allow_whitespace=>1 to constructor attributes achieves that effect. 


my $csv = Text: :CSV_XS->new({sep_char => Ssep_char, allow_whitespace=>1}) ; 
Output: 


a quoted, comma 
word 
word2 


e The library supports escaping special characters (quotes, separators) 


e The library supports configurable separator character, quote character, and escape character 





Documentatoin: http://search.cpan.org/perldoc/Text::CSV 
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Chapter 16: Object-oriented Perl 


Section 16.1: Defining classes in modern Perl 


Although available, defining a class from scratch is not recommended in modern Perl. Use one of helper OO 
systems which provide more features and convenience. Among these systems are: 


e Moose - inspired by Perl 6 OO design 
e Class: :Accessor - a lightweight alternative to Moose 


e Class: :Tiny - truly minimal class builder 


Moose 


package Foo; 
use Moose; 


has bar => (is => 'ro'); # a read-only property 
has baz => (is => 'rw', isa => 'Bool'); # a read-write boolean property 


sub qux { 
my $self = shift; 


my SbarIsBaz = Sself->bar eq 'baz'; # property getter 
Sself->baz(SbarIsBaz) ; # property setter 


Class::Accessor (Moose syntax) 


package Foo; 
use Class::Accessor ‘antlers’; 


has bar => (is => 'ro'); # a read-only property 


has baz => (is => 'rw', isa => 'Bool'); # a read-write property (only 'is' supported, the type is 
ignored) 


Class::Accessor (native syntax) 


package Foo; 
use base qw(Class: :Accessor) ; 


Foo->mk_accessors(qw(bar baz)); # some read-write properties 
Foo->mk_accessors(qw(qux) ) ; # a read-only property 


Class::Tiny 


package Foo; 
use Class::Tiny qw(bar baz); # just props 


Section 16.2: Creating Objects 


Unlike many other languages, Perl does not have constructors that allocate memory for your objects. Instead, one 
should write a class method that both create a data structure and populate it with data (you may know it as the 
Factory Method design pattern). 
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package Point; 
use strict; 


sub new { 
my ($class, $x, $y) = @_; 
my Sself = { x => $x, y => Sy }; # store object data in a hash 


bless Sself, Sclass; # bind the hash to the class 
return $self; 


This method can be used as follows: 
my Spoint = Point->new(1, 2.5); 


Whenever the arrow operator -> is used with methods, its left operand is prepended to the given argument list. So, 
@_ in new will contain values ('Point', 1, 2.5). 


There is nothing special in the name new. You can call the factory methods as you prefer. 
There is nothing special in hashes. You could do the same in the following way: 


package Point; 
use strict; 


sub new { 
my (Sclass, @coord) = @_; 
my $self = \@coord; 


bless $self, $class; 
return $self; 


In general, any reference may be an object, even a scalar reference. But most often, hashes are the most 
convenient way to represent object data. 


Section 16.3: Defining Classes 
In general, classes in Perl are just packages. They can contain data and methods, as usual packages. 


package Point; 
use strict; 


my SCANVAS_SIZE = [1000, 1000]; 
sub new { 
} 


sub polar_coordinates { 


} 
1; 
It is important to note that the variables declared in a package are class variables, not object (instance) variables. 


Changing of a package-level variable affects all objects of the class. How to store object-specific data, see in 
"Creating Objects". 
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What makes class packages specific, is the arrow operator ->. It may be used after a bare word: 
Point->new(...); 

or after a scalar variable (usually holding a reference): 
my @polar = Spoint->polar_coordinates; 

What is to the left of the arrow is prepended to the given argument list of the method. For example, after call 
Point->new(1, 2); 


array @_ in new will contain three arguments: ('Point', 1, 2). 


Packages representing classes should take this convention into account and expect that all their methods will have 


one extra argument. 


Section 16.4: Inheritance and methods resolution 


To make a class a subclass of another class, use parent pragma: 


package Point; 
use strict; 


1; 

package Point2D; 

use strict; 

use parent qw(Point) ; 

U 

package Point3D; 

use strict; 

use parent qw(Point) ; 

1; 

Perl allows for multiple inheritance: 


package Point2D; 

use strict; 

use parent qw(Point PlanarObject) ; 

1; 

Inheritance is all about resolution which method is to be called in a particular situation. Since pure Perl does not 


prescribe any rules about the data structure used to store object data, inheritance has nothing to do with that. 


Consider the following class hierarchy: 


package GeometryObject; 
use strict; 


sub transpose { ...} 
1 
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package Point; 

use strict; 

use parent qw(GeometryObject) ; 
sub new { ... }; 

1h 

package PlanarObject; 

use strict; 

use parent qw(GeometryObject) ; 
sub transpose { ... } 

le 

package Point2D; 

use strict; 

use parent qw(Point PlanarObject) ; 
sub new { ... } 

sub polar_coordinates { ... } 
a 


The method resolution works as follows: 


1. The starting point is defined by the left operand of the arrow operator. 


o If itis a bare word: 


Point2D->new(...); 
..or a scalar variable holding a string: 


my Sclass = 'Point2D'; 
Sclass->new(...); 


..then the starting point is the package with the corresponding name (Point2D in both examples). 
o If the left operand is a scalar variable holding a blessed reference: 


my Spoink = {oh 
bless Spoint, 'Point2D'; # typically, it is encapsulated into class methods 
my @coord = Spoint->polar_coordinates; 


then the starting point is the class of the reference (again, Point2D). The arrow operator cannot be 
used to call methods for unblessed references. 


2. If the starting point contains the required method, it is simply called. 


Thus, since Point2D: :new exists, 
Point2D->new(...); 
will simply call it. 
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3. If the starting point does not contain the required method, depth-first search in the parent classes is 
performed. In the example above, the search order will be as follows: 


o Point2D 

o Point (first parent of Point2D) 

o GeometryObject (parent of Point) 

o PlanarObject (second parent of Point2D) 


For example, in the following code: 


my Spoint = Point2D->new(...); 
Spoint->transpose(...); 


the method that will be called is Geomet ryObject : : transpose, even though it would be overridden in 
PlanarObject: : transpose. 


4. You can set the starting point explicitly. 


In the previous example, you can explicitly call PlanarObject : : transpose like so: 


my Spoint = Point2D->new(...); 
Spoint->PlanarObject: :transpose(...); 


5. In a similar manner, SUPER: : performs method search in parent classes of the current class. 


For example, 


package Point2D; 

use strict; 

use parent qw(Point PlanarObject) ; 
sub new { 


(my Sclass, $x, Sy) = @_; 
my $self = Sclass->SUPER: :new; 


ile 


will call Point : :new in the course of the Point2D: :new execution. 


Section 16.5: Class and Object Methods 


In Perl, the difference between class (static) and object (instance) methods is not so strong as in some other 
languages, but it still exists. 


The left operand of the arrow operator -> becomes the first argument of the method to be called. It may be either a 
string: 


# the first argument of new is string ‘Point’ in both cases 
Point->new(...); 


my $class = ‘Point’; 
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Sclass->new(...); 
or an object reference: 


# reference contained in Spoint is the first argument of polar_coordinates 
my Spoint = Point->new(...); 
my @coord = S$point->polar_coordinates; 


Class methods are just the ones that expect their first argument to be a string, and object methods are the ones 
that expect their first argument to be an object reference. 


Class methods typically do not do anything with their first argument, which is just a name of the class. Generally, it 
is only used by Perl itself for method resolution. Therefore, a typical class method can be called for an object as 
well: 


my Swidth = Point->canvas_width; 


my Spoint = Point->new(...); 
my Swidth = Spoint->canvas_width; 


Although this syntax is allowed, it is often misleading, so it is better to avoid it. 


Object methods receive an object reference as the first argument, so they can address the object data (unlike class 
methods): 


package Point; 
use strict; 


sub polar_coordinates { 
my (Spoint) = @_; 


my $x = ame o: 
my $y = $point->{y}; 


return (sqrt($x * $x + Sy * Sy), atan2(Sy, $x)); 


1; 
The same method can track both cases: when it is called as a class or an object method: 
sub universal_method { 
my $self = shift; 
if (ref Sself) { 
# object logic 


} 
else { 
# class logic 


Section 16.6: Roles 
A role in Perl is essentially 


e a set of methods and attributes which 
e injected into a class directly. 
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A role provides a piece of functionality which can be composed into (or applied to) any class (which is said to 
consume the role). A role cannot be inherited but may be consumed by another role. 


A role may also require consuming classes to implement some methods instead of implementing the methods itself 
(just like interfaces in Java or C#). 


Perl does not have built-in support for roles but there are CPAN classes which provide such support. 


Moose::Role 


package Chatty; 
use Moose: :Role; 


requires ‘introduce’; # a method consuming classes must implement 
sub greet { # a method already implemented in the role 


print "Hi!\n"; 


} 


package Parrot; 
use Moose; 


with ‘Chatty’; 
sub introduce { 


print "I'm Buddy.\n"; 
} 


Role::Tiny 


Use if your OO system does not provide support for roles (e.g. Class: :Accessor or Class: : Tiny). Does not support 
attributes. 


package Chatty; 
use Role: :Tiny; 


requires ‘introduce'; # a method consuming classes must implement 

sub greet { # a method already implemented in the role 
print "Hi!\n"; 

} 

package Parrot; 

use Class: :Tiny; 

use Role: :Tiny: :With; 

with ‘Chatty’; 

sub introduce { 


print "I'm Buddy.\n"; 
} 
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Chapter 17: Exception handling 


Section 17.1: eval and die 


This is the built-in way to deal with "exceptions" without relying on third party libraries like Try::Tiny. 


my Sret; 


eval { 
ret = some_function_that_might_die() ; 
1; 

y or do 4 
my Seval_error = $@ || "Zombie error!"; 
handle_error(Seval_error) ; 


Pe 


# use Sret 


We "abuse" the fact that die has a false return value, and the return value of the overall code block is the value of 
the last expression in the code block: 


e if $ret is assigned to successfully, then the 1; expression is the last thing that happens in the eval code 
block. The eval code block thus has a true value, so the or do block does not run. 

e if some_function_that_might_die() does die, then the last thing that happens in the eval code block is the 
die. The eval code block thus has a false value and the or do block does run. 

e The first thing you must do in the or do block is read $@. This global variable will hold whatever argument was 
passed to die. The || “Zombie Error" guard is popular, but unnecessary in the general case. 


This is important to understand because some not all code does fail by calling die, but the same structure can be 
used regardless. Consider a database function that returns: 


e the number of rows affected on success 
e '@ but true’ if the query is successful but no rows were affected 
e 9 if the query was not successful. 


In that case you can still use the same idiom, but you have to skip the final 1;, and this function has to be the last 
thing in the eval. Something like this: 


eval { 
my $value = My: :Database: :retrieve(Smy_thing); # dies on fail 
Svalue->set_status("Completed") ; 
Svalue->set_completed_timestamp(time()) ; 
Svalue->update(); # returns false value on fail 

} or do { # handles both the die and the @ return value 
my Seval_error = $@ || "Zombie error!"; 
handle_error(Seval_error) ; 
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Chapter 18: Regular Expressions 


Section 18.1: Replace a string using regular expressions 


s/foo/bar/; # replace "foo" with "bar" in S_ 

my $foo = "foo"; 

foo =~ s/foo/bar/; # do the above on a different variable using the binding operator =~ 

s~ foo ~ bar ~; # using ~ as a delimiter 

$foo = s/foo/bar/r; # non-destructive r flag: returns the replacement string without modifying the 
variable it's bound to 

s/foo/bar/g; # replace all instances 


Section 18.2: Matching strings 


The =~ operator attempts to match a regular expression (Set apart by /) to a string: 


my Sstr = “hello world"; 
print "Hi, yourself!\n" if Sstr =~ /‘hello/; 


/*‘hello/ is the actual regular expression. The ^ is a special character that tells the regular expression to start with 
the beginning of the string and not match in the middle somewhere. Then the regex tries to find the following 
letters in order h, e, 1, 1, and o. 


Regular expressions attempt to match the default variable ($_) if bare: 

$_ = "hello world"; 

print "Ahoy!\n" if /*hello/; 

You can also use different delimiters is you precede the regular expression with the m operator: 
m~*hello~; 

m{*hello}; 

m|*hello| ; 


This is useful when matching strings that include the / character: 


print "user directory" if m|‘*/usr]|; 


Section 18.3: Parsing a string with a regex 


Generally, it's not a good idea to use a regular expression to parse a complex structure. But it can be done. For 
instance, you might want to load data into hive table and fields are separated by comma but complex types like 
array are separated by a "|". Files contain records with all fields separated by comma and complex type are inside 
square bracket. In that case, this bit of disposable Perl might be sufficient: 





echo 12.13.451, 5,6 I7 el y(t, 25 34175" N 
perl -ne \ 
“while C SAUA WENN 

TEC VLC NIN eye 
Stext = $1; 
Stext_to_replace = $text; 
Stext =~ s/\,/\|/g; 
s/Stext_to_replace/S$text/; 
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} 
} print’ 


You'll want to spot check the output: 


1,2,[3|4|5],5,6,[7 | 8],[1 |2|34],5 


Section 18.4: Usage of \Q and \E in pattern matching 


What's between \Q and \E is treated as normal characters 
#!/usr/bin/perl 


my $str = "hello.it's.me"; 


my @test = ( 
"hello.it's.me", 
"hello/it's!me", 


Ve 
sub ismatched($) { $_[@] ? "MATCHED!" : "DID NOT MATCH!" } 


my @match = ( 
[| general_match=> sub { ismatched /Sstr/ } ], 
| ge_match => sub { ismatched /\QSstr\E/ } ] 
De 


for (@test) { 
primet | \Stringr= ss. s\n © 


foreach my Smethod (@match) { 
my(Sname, Smatch) = @Smethod; 
print " - $name: ", Smatch->(), "\n"; 


} 


Output 


String = ‘hello.it's.me': 
- general_match: MATCHED! 
- qe_match: MATCHED! 
String = ‘hello/it's!me': 
- general_match: MATCHED! 
- qe_match: DID NOT MATCH! 
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Chapter 19: XML Parsing 
Section 19.1: Parsing with XML::Twig 


#!/usr/bin/env perl 


use strict; 
use warnings ‘all’; 


use XML: :Twig; 
my Stwig = XML::Twig->parse( \*DATA ); 


#we can use the ‘root’ method to find the root of the XML. 
my $root = $twig->root; 


#first_child finds the first child element matching a value. 
my $title = Sroot->first_child('title') ; 


#text reads the text of the element. 
my S$title_text = Stitle->text; 


print "Title is: ", $title_text, "\n'; 


#The above could be combined: 
print Stwig ->root->first_child_text('title'), "\n"; 


## You can use the ‘children' method to iterate multiple items: 
my $list = $twig->root->first_child('list') ; 


#children can optionally take an element 'tag' - otherwise it just returns all of them. 
foreach my Selement ( S$list->children ) { 


#the ‘att' method reads an attribute 
print “Element with ID: ", Selement->att('id') // ‘none here', " is ", Selement->text, 
"\n": 


} 


#And if we need to do something more complicated, we an use 'xpath'. 
#get_xpath or findnodes do the same thing: 
#return a list of matches, or if you specify a second numeric argument, just that numbered match. 


#xpath syntax is fairly extensive, but in this one - we search: 
# anywhere in the tree: // 

#nodes called 'item' 

#with an id attribute [@id] 

#and with that id attribute equal to "1000". 

#by specifying '@' we say ‘return just the first match’. 


print "Item 1000 is: ", Stwig->get_xpath( '//item[@id="1000"]', © )->text, "\n"; 


#this combines quite well with ‘map’ to e.g. do the same thing on multiple items 
print "All IDs:\n", join ( "\n", map { $_ -> att('id') } Stwig -> get_xpath('//item')); 
#note how this also finds the item under 'summary', because of // 


__-DATA__ 
<?xml version="1.0" encoding="utf-8"?> 
<root> 
<title>some sample xml</title> 
<first key="value" key2="value2"> 
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<second>Some text</second> 
</first> 
<third> 
<fourth key3="value">Text here too</fourth> 
</third> 
<list> 
<item id="1">Item1</item> 
<item id="2">Item2</item> 
<item id="3">Item3</item> 
<item id="66">Item66</item> 
<item id="88">Item88</item> 
<item id="100">Item100</item> 
<item id="1000">Item1000</item> 


<notanitem>Not an item at all really.</notanitem> 


</list> 
<summary> 
<item id="no_id">Test</item> 
</summary> 
</root> 


Section 19.2: Consuming XML with XML::Rabbit 


With XML: :Rabbit it is possible to consume XML files easily. You define in a declarative way and with an XPath 
syntax what you are looking for in the XML and XML: :Rabbit will return objects according to the given definition. 


Definition: 


package Bookstore; 
use XML: :Rabbit: :Root; 


has_xpath_object_list books => './book' => ‘Bookstore: :Book’' ; 


finalize_class(); 


package Bookstore: :Book ; 

use XML: :Rabbit; 

has_xpath_value bookid => './@id'; 
has_xpath_value author => './author' ; 
has_xpath_value title => './title'; 
has_xpath_value genre => './genre'; 
has_xpath_value price => './price'; 
has_xpath_value publish_date => './publish_date' ; 
has_xpath_value description => './description’ ; 


has_xpath_object purchase_data => ' ./purchase_data' 


finalize_class(); 


package Bookstore: :Purchase; 

use XML: :Rabbit; 

has_xpath_value price => './price'; 
has_xpath_value date => './date'; 
finalize_class(); 


XML Consumption: 


use strict; 
use warnings; 
use utf8; 


package Library; 

use feature qw(say) ; 
use Carp; 

use autodie; 
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say "Showing data information"; 
my Sbookstore = Bookstore->new( file => './sample.xml' ); 


foreach my Sbook( @{Sbookstore->books} ) { 


say "ID: " . Sbook->bookid; 

say "Title: " . Sbook->title; 

say "Author: " . Sbook->author, "\n"; 
} 
Notes: 


Please be careful with the following: 


1. The first class has to be XML: :Rabbit: :Root. It will place you inside the main tag of the XML document. In our 
case it will place us inside <catalog> 


2. Nested classes which are optional. Those classes need to be accessed via a try/catch (or eval / $@ check) 
block. Optional fields will simply return nu11. For example, for purchase_data the loop would be: 


foreach my Sbook( @{Sbookstore->books} ) { 


say "ID: " . Sbook->bookid; 
say "Title: " . Sbook->title; 
say “Author: " . Sbook->author; 
try { 
say "Purchase price: ". Sbook->purchase_data->price, "\n"; 
} catch { 
say "No purchase price available\n" ; 
} 
} 
sample.xml 


<?xml version="1.0"?> 
<catalog> 

<book id="bk101"> 
<author>Gambardella, Matthew</author> 
<title>XML Developer's Guide</title> 
<genre>Computer</genre> 
<price>44 .95</price> 
<publish_date>2000-10-01</publish_date> 
<description>An in-depth look at creating applications 
with XML.</description> 

</book> 

<book id="bk102"> 
<author>Ralls, Kim</author> 
<title>Midnight Rain</title> 
<genre>Fantasy</genre> 
<price>5.95</price> 
<publish_date>2000-12-16</publish_date> 
<description>A former architect battles corporate zombies, 
an evil sorceress, and her own childhood to become queen 
of the world.</description> 

</book> 

<book id="bk103"> 
<author>Corets, Eva</author> 
<title>Maeve Ascendant</title> 
<genre>Fantasy</genre> 
<price>5.95</price> 
<publish_date>2000-11-17</publish_date> 
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<description>After the collapse of a nanotechnology 
society in England, the young survivors lay the 
foundation for a new society.</description> 

</book> 

<book id="bk104"> 
<author>Corets, Eva</author> 
<title>Oberon's Legacy</title> 
<genre>Fantasy</genre> 
<price>5.95</price> 
<publish_date>2001-03-10</publish_date> 
<description>In post-apocalypse England, the mysterious 
agent known only as Oberon helps to create a new life 
for the inhabitants of London. Sequel to Maeve 
Ascendant .</description> 
<purchase_data> 

<date>2001-12-21</date> 
<price>20</price> 

</purchase_data> 

</book> 

</catalog> 


Section 19.3: Parsing with XML::LibXML 


# This uses the 'sample.xml' given in the XML::Twig example. 


# Module requirements (1.70 and above for use of load_xml) 
use XML::LibXML '1.70'; 


# let's be a good perl dev 
use strict; 
use warnings ‘all’; 


# Create the LibXML Document Object 
my $xml = XML: :LibXML->new() ; 


# Where we are retrieving the XML from 
my $file = ‘sample.xml' ; 


# Load the XML from the file 
my $dom = XML: :LibXML->load_xm1( 
location => $file 


Dy 


# get the docroot 
my Sroot = Sdom->getDocumentElement ; 


# if the document has children 
if(Sroot->hasChildNodes) { 


# getElementsByLocalName returns a node list of all elements who's 
# localname matches ‘title’, and we want the first occurrence 

# (via get_node(1)) 

my $title = Sroot->getElementsByLocalName('title' ); 


if(defined $title) { 
# Get the first matched node out of the nodeList 
my $node = S$title->get_node(1); 


# Get the text of the target node 
my Stitle_text = Snode->textContent; 


Goalkicker.com - Perl® Notes for Professionals 


60 


print "The first node with name ‘title’ contains: $title_text\n"; 


} 


# The above calls can be combined, but is possibly prone to errors 

# (if the getElementsByLocalName() failed to match a node). 

# 

# my Stitle_text = Sroot->getElementsByLocalName('title')->get_node(1)->textContent; 


} 


# Using Xpath, get the price of the book with id 'bk104' 
# 


# Set our xpath 
my xpath = q!/catalog/book[@id='bk1@4' ]/price! ; 


# Does that xpath exist? 
if(Sroot->exists(Sxpath)) { 


# Pull in the twig 
my Smatch = Sroot->find(Sxpath) ; 


if(defined Smatch) { 
# Get the first matched node out of the nodeList 
my $node = Smatch->get_node(1); 


# pull in the text of that node 
my Smatch_text = Snode->textContent; 


print "The price of the book with id bk104 is: Smatch_text\n'; 
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Chapter 20: Unicode 


Section 20.1: The utf8 pragma: using Unicode in your sources 


The utf8 pragma indicates that the source code will be interpreted as UTF-8. Of course, this will only work if your 
text editor is also saving the source as UTF-8 encoded. 


Now, string literals can contain arbitrary Unicode characters; identifiers can also contain Unicode but only word-like 
characters (see perldata and perlrecharclass for more information): 





use utf8; 

my Svar1 = '§?§©????'; # works fine 

my $? = 4; # works since ? is a word (matches \w) character 
my $p§2 = 3; # does not work since § is not a word character. 


say "ya" if Svar1 =~ /?§/; # works fine (prints "ya") 


Note: When printing text to the terminal, make sure it supports UTF-8.* 


There may be complex and counter-intuitive relationships between output and source encoding. Running ona 
UTF-8 terminal, you may find that adding the utf8 pragma seems to break things: 


S$ perl -e ‘print "Mggse\n 


Moose 

S$ perl -Mutf8 -e ‘print "Mggse\n"' 
M??se 

$ perl -Mutf8 -CO -e ‘print "Mggse\n"' 
Moose 


In the first case, Perl treats the string as raw bytes and prints them like that. As these bytes happen to be valid 
UTF-8, they look correct even though Perl doesn't really know what characters they are (e.g. length("Mogse") will 
return 7, not 5). Once you add -Mutf8, Perl correctly decodes the UTF-8 source to characters, but output is in Latin-1 
mode by default and printing Latin-1 to a UTF-8 terminal doesn't work. Only when you switch STDOUT to UTF-8 using 
-CO will the output be correct. 


use utf8 doesn't affect standard I/O encoding nor file handles! 


Section 20.2: Handling invalid UTF-8 


Reading invalid UTF-8 


When reading UTF-8 encoded data, it is important to be aware of the fact the UTF-8 encoded data can be invalid or 
malformed. Such data should usually not be accepted by your program (unless you know what you are doing). 
When unexpectedly encountering malformed data, different actions can be considered: 


e Print stacktrace or error message, and abort program gracefully, or 
e Insert a substitution character at the place where the malformed byte sequence appeared, print a warning 
message to STDERR and continue reading as nothing happened. 


By default, Perl will warn you about encoding glitches, but it will not abort your program. You can make your 
program abort by making UTF-8 warnings fatal, but be aware of the caveats in Fatal Warnings. 


The following example writes 3 bytes in encoding ISO 8859-1 to disk. It then tries to read the bytes back again as 
UTF-8 encoded data. One of the bytes, @xE5, is an invalid UTF-8 one byte sequence: 
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use strict; 
use warnings; 
use warnings FATAL => ‘utf8'; 


binmode STDOUT, ':utf8'; 

binmode STDERR, ':utf8'; 

my Sbytes = "\x{61}\x{E5}\x{61}"; #3 bytes in iso 8859-1: aaa 

my Sfn = ‘'test.txt'; 

open ( my $fh, '>:raw', Sfn ) or die "Could not open file 'Sfn': $!"; 
print Sfh Sbytes; 

close Sfh; 

open ( fh, "<:encoding(utf-8)", Sfn ) or die "Could not open file '$fn': $!"; 
my Sstr = do { local $/; <Sfh> }; 

close Sfh; 

print "Read string: '$str'\n"; 


The program will abort with a fatal warning: 
utf8 "\xE5" does not map to Unicode at ./test.pl line 10. 


Line 10 is here the second last line, and the error occurs in the part of the line with <Sfh> when trying to read a line 
from the file. 


If you don't make warnings fatal in the above program, Perl will still print the warning. However, in this case it will 
try to recover from the malformed byte @xE5 by inserting the four characters \xE5 into the stream, and then 
continue with the next byte. As a result, the program will print: 


Read string: 'a\xE5a' 


Section 20.3: Command line switches for one-liners 
Enable utf8 pragma 


In order to enable utf8 pragma in one-liner, perl interpreter should be called with -Mutf8 option: 


perl -Mutf8 -E ‘my SA = "human"; say SA' 
Unicode handling with -C switch 


The -C command line flag lets you control Unicode features. It can be followed by a list of option letters. 


Standard I/O 


e I -STDIN will be in UTF-8 

e 0 - STDOUT will be in UTF-8 

E - STDERR will be in UTF-8 

e S- shorthand for IOE, standard I/O streams will be in UTF-8 


echo "Mataidtng yataiothtwv" | perl -CS -Mutf8 -nE ‘say "ok" if /Mataiótng/ ' 


Script's arguments 


e A- treats @ARGV as an array of UTF-8 encoded strings 


perl -CA -Mutf8 -E ‘my Sarg = shift; say "anteater" if Sarg eq "mypasbeg"' mypaBbea 
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Default PerllO layer 


e i- UTF-8 is the default PerllO layer for input streams 
e o - UTF-8 is the default PerllO layer for output streams 
D - shorthand for io 


perl -CD -Mutf8 -e ‘open my Sfh, ">", “utf8.txt" or die $!; print $fh "740| 2AlsH"' 


-M and -C switches may be combined: 


perl -CASD -Mutf8 -E ‘say "Mataldtng pataioTATwv\n"' ; 


Section 20.4: Standard I/O 


The encoding to be used for the standard I/O filehandles (STDIN, STDOUT, and STDERR), can be set separately for each 
handle using binmode: 


binmode STDIN, ':encoding(utf-8)'; 


binmode STDOUT, ':utf8'; 
binmode STDERR, ' :utf8'; 


Note: when reading one would in general prefer :encoding(utf-8) over :utf8, see Remarks for more information. 
Alternatively, you can use the open pragma. 

# Setup such that all subsequently opened input streams will use ':encoding(utf-8) ' 
# and all subsequently opened output streams will use ':utf8' 

# by default 

use open (IN => ':encoding(utf-8)', OUT => ':utf8'); 

# Make the (already opened) standard file handles inherit the setting 

# given by the IO settings for the open pragma 

use open ( :std ); 

# Now, STDIN has been converted to ':encoding(utf-8)', and 

# STDOUT and STDERR have ':utf8' 


Alternatively, to set all filehandles (both those yet to be opened and also the standard ones) to use 
:encoding(utf-8): 


use open qw( :encoding(utf-8) :std ); 


Section 20.5: File handles 


Setting encoding with open() 


When opening a text file, you may specify it's encoding explicitly with a three-argument open(). This en-/decoder 
attached to a file handle is called an "I/O layer": 


my $filename = '/path/to/file' ; 
open my Sfh, '<:encoding(utf-8)', $filename or die “Failed to open $filename: $!"; 


See Remarks for a discussion of the differences between :utf8 and :encoding(utf-8). 
Setting encoding with binmode() 


Alternatively, you may use binmode() to set the encoding for individual file handle: 
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my $filename = '/path/to/file' ; 


open my Sfh, '<', $filename or die "Failed to open $filename: $!"; 
binmode Sfh, ‘':encoding(utf-8)'; 


open pragma 


To avoid setting encoding for each file handle separately, you may use the open pragma to set a default I/O layer 
used by all subsequent calls to the open() function and similar operators within the lexical scope of this pragma: 


# Set input streams to ':encoding(utf-8)' and output streams to ':utf8' 
use open (IN => ':encoding(utf-8)', OUT => ':utf8'); 
# Or to set all input and output streams to ':encoding(utf-8) ' 


use open ':encoding(utf-8)'; 


Setting encoding with command line -C flag 


Finally, it is also possible to run the perl interpreter with a -CD flag that applies UTF-8 as the default I/O layer. 
However, this option should be avoided since it relies on specific user behaviour which cannot be predicted nor 
controlled. 


Section 20.6: Create filenames 


The following examples use the UTF-8 encoding to represent filenames (and directory names) on disk. If you want 
to use another encoding, you should use Encode: :encode(...). 





use v5.14; 

# Make Perl recognize UTF-8 encoded characters in literal strings. 
# For this to work: Make sure your text-editor is using UTF-8, so 
# that bytes on disk are really UTF-8 encoded. 

use utf8; 


# Ensure that possible error messages printed to screen are converted to UTF-8. 
# For this to work: Check that your terminal emulator is using UTF-8. 

binmode STDOUT, ':utf8'; 

binmode STDERR, ':utf8'; 


my $filename = 'æ€ 


; # $filename is now an internally UTF-8 encoded string. 


# Note: in the following it is assumed that Sfilename has the internal UTF-8 

# flag set, if Sfilename is pure ASCII, it will also work since its encoding 

# overlaps with UTF-8. However, if it has another encoding like extended ASCII, 
# Sfilename will be written with that encoding and not UTF-8. 

# Note: it is not necessary to encode $filename as UTF-8 here 

# since Perl is using UTF-8 as its internal encoding of Sfilename already 


# Example1 -- using open() 
open ( my $fh, '>', $filename ) or die "Could not open ‘$filename’: $!"; 
close $fh; 


# Example2 -- using qx() and touch 
qx{touch $filename}; 


# Example3 -- using system() and touch 
system 'touch', $filename; 


# Example4 -- using File::Touch 


use File: :Touch; 
eval { touch( $filename ) }; die "Could not create file 'Sfilename': $!" if $0; 
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Section 20.7: Read filenames 


Perl does not attempt to decode filenames returned by builtin functions or modules. Such strings representing 
filenames should always be decoded explicitly, in order for Perl to recognize them as Unicode. 


use v5.14; 
use Encode qw(decode_utf8) ; 


# Ensure that possible error messages printed to screen are converted to UTF-8. 
# For this to work: Check that you terminal emulator is using UTF-8. 

binmode STDOUT, ':utf8'; 

binmode STDERR, ':utf8'; 


# Example1 -- using readdir() 
my scan =r 
opendir(my $dh, $dir) or die "Could not open directory 'Sdir': $!"; 
while (my $filename = decode_utf8(readdir $dh)) { 
# Do something with Sfilename 
} 
close Sdh; 


# Example2 -- using getcwd() 
use Cwd qw(getcwd) ; 
my $dir = decode_utf8( getcwd() ); 


# Example3 -- using abs2rel1() 
use File: :Spec; 

use utf8; 

my Sbase = 'g'; 


my $path = "Sbase/b/z"; 

my Srelpath = decode_utf8( File::Spec->abs2rel( $path, Sbase ) ); 

# Note: If you omit Sbase, you need to encode Spath first: 

use Encode qw(encode_utf8) ; 

my Srelpath = decode_utf8( File::Spec->abs2rel( encode_utf8( $path ) ) ); 


# Example4 -- using File::Find::Rule (part1 matching a filename) 

use File: :Find: :Rule; 

use utf8; 

use Encode qw(encode_utf8) ; 

my $filename = 'æ'; 

# File::Find::Rule needs $filename to be encoded 

my @files = File: :Find: :Rule->new->name( encode_utf8(S$filename) )->in('.'); 
$_ = decode_utf8( $_ ) for @files; 


# Example5 -- using File::Find::Rule (part2 matching a regular expression) 
use File: :Find: :Rule; 
use utf8; 


my Spat = '[e].$'; # Unicode pattern 
# Note: In this case: File::Find::Rule->new->name( qr/Spat/ )->in('.') 
# will not work since Spat is Unicode and filenames are bytes 
# Also encoding Spat first will not work correctly 
my @files; 
File: :Find: :Rule->new->exec( sub { wanted( Spat, \@files ) } )->in('.'); 
S_ = decode_utf8( $_ ) for @files; 
sub wanted { 
my ( Spat, S$files ) = @_; 
my Sname = decode_utf8( S_ ); 
my Sfull_name = decode_utf8( S$File::Find::name ); 
push @Sfiles, $full_name if $name =~ /Spat/; 
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Note: if you are concerned about invalid UTF-8 in the filenames, the use of decode_utf8( ... ) in the above 
examples should probably be replaced by decode( ‘utf-8', ... ). This is because decode_utf8( ... )isa 
synonym for decode( ‘utf8', ... ) and there is a difference between the encodings utf-8 and utf8 (see 
Remarks below for more information) where utf-8 is more strict on what is acceptable than utf8. 
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Chapter 21: Perl one-liners 


Section 21.1: Upload file into mojolicious 


perl -Mojo -E 'p("http://localhost:3000" => form => {Input_Type => "XML", Input_File => {file => 
"d:/xml/test.xml"}})' 


File d: /xm1/test .xm1 will be uploaded to server which listen connections on localhost :3900 (Source) 
In this example: 


-Mmodule executes use module; before executing your program 
-E commandline is used to enter one line of program 
If you have no ojo module you can use cpanm ojo command to install it 


To read more about how to run perl use perldoc perlrun command or read here 

Section 21.2: Execute some Perl code from command line 
Simple one-liners may be specified as command line arguments to perl using the -e switch (think "execute"): 
perl -e'print "Hello, World!\n"' 

Due to Windows quoting rules you can't use single-quoted strings but have to use one of these variants: 


perl -e"print qq(Hello, World!\n)" 
perl -e"print \"Hello, World! \n\"" 


Note that to avoid breaking old code, only syntax available up to Perl 5.8.x can be used with -e. To use anything 


newer your perl version may support, use -E instead. E.g. to use say available from 5.10.0 on plus Unicode 6.0 from 
>=v5.14.0 (also uses -CO to make sure STDOUT prints UTF-8): 


Version = 5.14.0 


perl -CO -E'say "\N{PILE OF POO}"' 


el 21.3: Using double-quoted strings in Windows one- 
iners 


Windows uses only double quotes to wrap command line parameters. In order to use double quotes in perl one- 
liner (i.e. to print a string with an interpolated variable), you have to escape them with backslashes: 


perl -e "my Sgreeting = ‘Hello'; print \"Sgreeting, world! \n\"" 
To improve readability, you may use a qq() operator: 


perl -e "my Sgreeting = 'Hello'; print qq(Sgreeting, world! \n)" 


Section 21.4: Print lines matching a pattern (PCRE grep) 


perl -ne'print if /foo/' file.txt 


Case-insensitive: 
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perl -ne'print if /foo/i' file.txt 


Section 21.5: Replace a substring with another (PCRE sed) 
perl -pe"s/foo/bar/g" file.txt 

Or in-place: 

perl -i -pe's/foo/bar/g' file.txt 

On Windows: 


perl -i.bak -pe"s/foo/bar/g" file.txt 


Section 21.6: Print only certain fields 


perl -lane'print "SF[@] SF[-1]"' data.txt 
# prints the first and the last fields of a space delimited record 


CSV example: 


perl -F, -lane'print "SF[@] SF[-1]"' data.csv 


Section 21.7: Print lines 5 to 10 


perl -ne'print if 5..10' file.txt 


Section 21.8: Edit file in-place 





Without a backup copy (not supported on Windows) 
perl -i -pe's/foo/bar/g' file.txt 
With a backup copy file.txt.bak 
perl -i.bak -pe's/foo/bar/g' file.txt 
With a backup copy old_file.txt.orig in the backup subdirectory (provided the latter exists): 


perl -i'backup/old_*.orig' -pe's/foo/bar/g' file.txt 


Section 21.9: Reading the whole file as a string 
perl -0777 -ne'print "The whole file as a string: --->$_<---\n"' 


Note: The -0777 is just a convention. Any -04900 and above would de the same. 
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Chapter 22: Randomness 


Section 22.1: Accessing an array element at random 


my @letters = ( 'a' .. ‘z' ); # English ascii-bet 


print Sletters[ rand @letters ] for 1 .. 5; # prints 5 letters at random 


How it works 


e rand EXPR expects a scalar value, So @letters is evaluated in scalar context 

e An array in scalar context returns the number of elements it contains (26 in this case) 

e rand 26 returns a random fractional number in the interval ð < VALUE < 26. (It can never be 26) 

e Array indices are always integers, so Sletters[rand @letters] =S$letters[int rand @letters] 

e Perl arrays are zero-indexed, so Sarray[rand @array] returns Sarray[®], Sarray[S#array] or an element in 
between 


(The same principle applies to hashes) 


my %colors = ( red => ØxFF000O, 
green => Qx@O0FFOO, 
blue => @0x000OFF, 


) 


print ( values %colors )[rand keys %colors] ; 


Section 22.2: Generate a random integer between 0 and 9 
Cast your random floating-point number as an int. 

Input: 

my Srange = 10; 


# create random integer as low as @ and as high as 9 


my Srandom = int(rand(Srange));  # max value is up to but not equal to Srange 
print Srandom . "\n"; 
Output: 


A random integer, like... 


See also the perldoc for rand. 





Goalkicker.com - Perl® Notes for Professionals 70 


Chapter 23: Special variables 


Section 23.1: Special variables in perl: 
1. $_: The default input and pattern-searching space. 
Example 1: 


my @array_variable = (1 2 3 4); 
foreach (@array_variable) { 

print 9 AN # $_ will get the value 1,2,3,4 in loop, if no other variable is supplied. 
} 


Example 2: 


while (<FH>){ 
chomp($_); # $_ refers to the iterating lines in the loop. 
} 


The following functions use $_ as a default argument: 


abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, 
evalbytes, exp, fc, glob, hex, int, lc, lcfirst, length, log, 
lstat, mkdir, oct, ord, pos, print, printf, quotemeta, readlink, 
readpipe, ref, require, reverse (in scalar context only), rmdir, 
say, sin, split (for its second argument), sqrt, stat, study, 
uc, ucfirst, unlink, unpack. 


2. @_: This array contains the arguments passed to subroutine. 
Example 1: 


example_sub( Stest1, Stest2, Stest3 ); 
sub example_sub { 


my ( Stest1, Stest2, Stest3 ) = @_; 
} 


Within a subroutine the array @_ contains the arguments passed to that subroutine. Inside a subroutine, @_ is the 
default array for the array operators pop and shift. 
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Chapter 24: Packages and modules 


Section 24.1: Using a module 


use Cwd; 


This will import the Cwd module at compile time and import its default symbols, i.e. make some of the module's 
variables and functions available to the code using it. (See also: perldoc -f use.) 


Generally this is will do the right thing. Sometimes, however, you will want to control which symbols are imported. 
Add a list of symbols after the module name to export: 


use Cwd ‘abs_path' ; 

If you do this, only the symbols you specify will be imported (ie, the default set will not be imported). 
When importing multiple symbols, it is idiomatic to use the qw( ) list-building construct: 

use Cwd qw(abs_path realpath) ; 

Some modules export a subset of their symbols, but can be told to export everything with :al1: 

use Benchmark ':all'; 


(Note that not all modules recognize or use the :a11 tag). 


Section 24.2: Using a module inside a directory 


use lib ‘includes'; 
use MySuperCoolModule ; 


use lib ‘includes’ ; adds the relative directory includes/ as another module search path in @INC. So assume 
that you have a module file MySyperCoolModule.pm inside includes/, which contains: 


package MySuperCoolModule ; 


If you want, you can group as many modules of your own inside a single directory and make them findable with 
one use lib statement. 


At this point, using the subroutines in the module will require prefixing the subroutine name with the package 
name: 


MySuperCoolModule: :SuperCoolSub_1("Super Cool String"); 


To be able to use the subroutines without the prefix, you need to export the subroutine names so that they are 
recognised by the program calling them. Exporting can be set up to be automatic, thus: 


package MySuperCoolModule ; 
use base ‘Exporter' ; 
our @EXPORT = ('SuperCoolSub_1', 'SuperCoolSub_2’ ) ; 


Then in the file that uses the module, those subroutines will be automatically available: 
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use MySuperCoolModule ; 
SuperCoolSub_1("Super Cool String"); 


Or you can set up the module to conditionally export subroutines, thus: 
package MySuperCoolModule ; 


use base '‘Exporter' ; 
our @EXPORT_OK = ('SuperCoolSub_1', '‘SuperCoolSub_2') ; 


In which case, you need to explicitly request the desired subroutines to be exported in the script that uses the 
module: 


use MySuperCoolModule 'SuperCoolSub_1' ; 
SuperCoolSub_1("Super Cool String"); 


Section 24.3: Loading a module at runtime 


require Exporter; 


This will ensure that the Exporter module is loaded at runtime if it hasn't already been imported. (See also: perldoc 
-f require.) 


N.B.: Most users should use modules rather than require them. Unlike use, require does not call the module's 
import method and is executed at runtime, not during the compile. 


This way of loading modules is useful if you can't decide what modules you need before runtime, such as with a 
plugin system: 
package My: :Module; 
my @plugins = qw( One Two ); 
foreach my Splugin (@plugins) { 
my Smodule = __PACKAGE__ . "::Plugins::$plugin"; 
module =~ s!::!/!g; 
require "Smodule.pm"; 


This would try to load My: :Package: :Plugins: :One and My: :Package: :Plugins: : Two. @plugins should of course 
come from some user input or a config file for this to make sense. Note the substitution operator s!::!/!g that 
replaces each pair of colons with a slash. This is because you can load modules using the familiar module name 
syntax from use only if the module name is a bareword. If you pass a string or a variable, it must contain a file 
name. 


Section 24.4: CPAN.pm 


CPAN.pm is a Perl module which allows to query and install modules from CPAN sites. 


It supports interactive mode invoked with 
cpan 
or 


perl -MCPAN -e shell 
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Querying modules 


By name: 
cpan> m MooseX: :YAML 
By a regex against module name: 


cpan> m /4XML::/ 


Note: to enable a pager or redirecting to a file use | or > shell redirection (spaces are mandatory around the | and >), e.g.: 


m /4XML::/ | less 

By distribution: 

cpan> d LMC/Net-Squid-Auth-Engine-@.04.tar.gz 
Installing modules 

By name: 

cpan> install MooseX: :YAML 

By distribution: 


cpan> install LMC/Net-Squid-Auth-Engine-9.04.tar.gz 


Section 24.5: List all installed modules 


From command line: 
cpan -1 
From a Perl script: 


use ExtUtils: :Installed; 
my Sinst = ExtUtils: :Installed->new() ; 
my @modules = S$inst->modules(); 


Section 24.6: Executing the contents of another file 
do a /contig- pl: 


This will read in the contents of the config.pl file and execute it. (See also: perldoc -f do.) 


N.B.: Avoid do unless golfing or something as there is no error checking. For including library modules, use require 


or use. 
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Chapter 25: Install Perl modules via CPAN 


Section 25.1: coanminus, the lightweight configuration-free 
replacement for cpan 


Usage 
To install a module (assuming cpanm is already installed): 


cpanm Data: :Section 


cpanm ("Cpanminus") strives to be less verbose than cpan but still captures all of the installation information in a log 
file in case it is needed. It also handles many "interactive questions" for you, whereas cpan doesn't. 


cpanm is also popular for installing dependencies of a project from, e.g., GitHub. Typical use is to first cd into the 
project's root, then run 


cpanm --installdeps . 


With --installdeps it will: 


1. Scan and install configure_requires dependencies from either 

o META,json 

o META.yml (if META.json is missing) 
2. Build the project (equivalent to perl Build. PL), generating MYMETA files 
3. Scan and install requires dependencies from either 

o MYMETA.json 

o MYMETA.yml (if MYMETA.json is missing) 


To specify the file 'some.cpanfile', containing the dependencies, run: 
cpanm --installdeps --cpanfile some.cpanfile . 
cpann Installation 


There are several ways to install it. Here's installation via cpan: 





cpan App: :cpanminus 
cpanm Configuration 


There is no config file for cpanm. Rather, it relies on the following environment variables for its configuration: 


e PERL_CPANM_OPT (General cpanm command line options) 

o export PERL_CPANM_OPT="--prompt" # in .bashrc, to enable prompting, e.g. 

o setenv PERL_CPANM_OPT "--prompt" # in .tcshrc 
e PERL_MM_OPT (ExtUtils::MakeMaker command line options, affects module install target) 
e PERL_MB_OPT (Module::Build command line options, affects module install target) 


Section 25.2: Installing modules manually 


If you don't have permissions to install perl modules, you may still install them manually, indicating a custom path 
where you've got writing permissions. 
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Fist, download and unzip module archive: 


wget module.tar.gz 
tar -xzf module.tar.gz 
cd module 


Then, if the module distribution contains a Makefile.PL file, run: 


perl Makefile.PL INSTALL_BASE=SHOME/per1 
make 

make test 

make install 


or if you have Build. PL file instead of a Makefile.PL: 


perl Build.PL --install_base SHOME/per1l 
perl Build 

perl Build test 

perl Build install 


You also have to include the module path in PERL5LIB environment variable in order to use it in your code: 


export PERL5LIB=SHOME/perl 


Section 25.3: Run Perl CPAN in your terminal (Mac and Linux) 
or command prompt (Windows) 


Command line 
You can use cpan to install modules directly from the command line: 


cpan install DBI 


This would be followed by possibly many pages of output describing exactly what it is doing to install the module. 


Depending on the modules being installed, it may pause and ask you questions. 
Interactive Shell 
You can also enter a "shell" thus: 


perl -MCPAN -e "shell" 


It will produce output as below: 


Terminal does not support AddHistory. 


cpan shell -- CPAN exploration and modules installation (v2.00) 
Enter 'h' for help. 


cpan|[ 1 |> 


Then you can install the modules which you want by the easy command install <module>. 


Example: cpan[1]> install DBI 
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After installing successfully, type exit to quit. 
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Chapter 26: Easy way to check installed 
modules on Mac and Ubuntu 


oem 26.1: Use perldoc to check the Perl package install 
pat 


$ perldoc -1 Time: :Local 


Section 26.2: Check installed perl modules via terminal 


Type below commana: 
instmodsh 


It'll show you the guild as below: 


Available commands are: 


1 - List all installed modules 
m <module> - Select a module 
q - Quit the program 

cmd? 


Then type 1 to list all the installed modules, you can also use command m <module> to select the module and get its 


information. 


After finish, just type q to quit. 


Section 26.3: How to check Perl corelist modules 


$ corelist -v v5.23.1 
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Chapter 27: Pack and unpack 


Section 27.1: Manually Converting C Structs to Pack Syntax 


If you're ever dealing with C Binary API's from Perl Code, via the syscall, ioctl, or fent1 functions, you need to 
know how to construct memory in a C Compatible way. 


For instance, if you were ever dealing with some function that expected a timespec, you'd look into 
/usr/include/time.h and find: 


struct timespec 

{ 
__time_t tv_sec; /* Seconds. */ 
__syscall_slong_t tv_nsec; /%* Nanoseconds. */ 


y 
You do a dance with cpp to find what that really means: 


cpp -E /usr/include/time.h -o /dev/stdout | grep __time_t 

# typedef long int __time_t; 

cpp -E /usr/include/time.h -o /dev/stdout | grep __syscall_slong_t 
# typedef long int __syscall_slong_t 


So its a (signed) int 


echo ‘void main(){ printf("%#1x\n", sizeof(__syscall_slong_t)); }' | 
gcc -x c -include stdio.h -include time.h - -o /tmp/a.out && /tmp/a.out 
# 0x8 


And it takes 8 bytes. So 64bit signed int. And I'm on a 64Bit Processor. =) 
Perldoc pack says 

q A signed quad (64-bit) value. 
So to pack a timespec: 


sub packtime { 
my ( Sconfig ) = @_; 
return pack ‘qq', @{Sconfig}{qw( tv_sec tv_nsec )}; 


And to unpack a timespec: 
sub unpacktime { 
my ( Sbuf ) = @; 
my Sout = {}; 
@{Sout}{qw( tv_sec tv_nsec )} = unpack 'qq', Sbuf; 
return Sout; 


Now you can just use those functions instead. 


my Stimespec = packtime({ tv_sec => ð, tv_nsec => @ }); 
syscall( ..., Stimespec ); # some syscall that reads timespec 
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later ... 
syscall( ..., Stimespec ); # some syscall that writes timespec 
print Dumper( unpacktime( Stimespec )); 


Section 27.2: Constructing an IPv4 header 


Sometimes you have to deal with structures defined in terms of C data types from Perl. One such application is the 
creation of raw network packets, in case you want to do something fancier than what the regular socket API has to 
offer. This is just what pack() (and unpack() of course) is there for. 


The obligatory part of an IP header is 20 octets (AKA "bytes") long. As you can see behind this link, source and 
destination IP address make up the last two 32-bit values in the header. Among the other fields are some with 16 
bits, some with 8 bits, and a few smaller chunks between 2 and 13 bits. 





Assuming we have the following variables to stuff into our header: 


my ($dscp, Secn, Slength, 
Sid, S$flags, $frag_off, 
Sttl, Sproto, 
Ssre ip, 
Sdst_ip); 


Note that three fields from the header are missing: 


e The version is always 4 (it's IPv4 after all) 
e IHLis 5in our example as we don't have an options field; length is specified in units of 4 octets so 20 octets 
gives a length of 5. 


e The checksum can be left at 0. Actually we'd have to calculate it but the code to do this doesn't concern us 
here. 


We could try and use bit operations to construct e.g. the first 32 bits: 
my Shdr = 4 << 28 | 5 << 24 | Sdscp << 18 | Secn << 16 | S$length; 


This approach only works up to the size of an integer though, which is usually 64 bits but can be as low as 32. 
Worse, it depends on the CPU's endianness so it will work on some CPUs and fail on others. Let's try pack(): 


my Shdr = pack('H2B8n', '45', sprintf("%@6b%@2b", Sdscp, Secn), $length); 


The template first specifies H2, a 2-character hex string, high nybble first. The corresponding argument to pack is 
"45"—version 4, length 5. The next template is B8, an 8-bit bit string, descending bit order inside each byte. We need to 
use bit strings to control layout down to chunks smaller than a nybble (4 bits), so the sprintf () is used to construct 
such a bit string from 6 bits from Sdscp and 2 from Secn. The last one is n, an unsigned 16-bit value in Network Byte 
Order, i.e. always big-endian no matter what your CPU's native integer format is, and it is filled from Slength. 


That's the first 32 bits of the header. The rest can be built similarly: 


Template Argument Remarks 
n Sid 
sprintf ("%03b%813b", Sflags, 
B16 $frag_off) Same as DSCP/ECN 
C2 $ttl, Sproto Two consecutive unsigned octets 


x could be used to insert a null byte but n lets us specify an 


Q 
a / Seheeksue argument should we choose to calculate a checksum 
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use a4a4 to pack the result of two gethostbyname() calls as it 


N2 i d i 
Sst apnesesE ae is in Network Byte Order already! 


So the complete call to pack an IPv4 header would be: 


my $hdr = pack('H2B8n2B16C2nN2' , 
'45', sprintf("%@6b%82b", Sdscp, Secn), S$length, 
Sid, sprintf("%@3b%013b", Sflags, Sfrag_off), 
Sttl, Sproto, 0, 
Ssre ip, Sdst ip 

); 
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Chapter 28: Perl commands for Windows 
Excel with Win32::OLE module 


Parameters Details 
The name of the range. This must be an A1-style reference in the language of the macro. It can 
Cell1 (required) include the range operator (a colon), the intersection operator (a space), or the union operator (a 
comma). 


If specified, Cell1 corresponds to the upper-left corner of the range and Cell2 corresponds to the 


Cella (opuonal) lower-right corner of the range 


These examples introduce the most used commands of Perl to manipulate Excel via Win32::OLE module. 


Section 28.1: Opening and Saving Excel/Workbooks 


#Modules to use 

use Cwd '‘abs_path'; 

use Win32::OLE; 

use Win32::OLE qw(in with); 

use Win32::OLE::Const "Microsoft Excel"; 
SWin32::0LE::Warn = 3; 


#Need to use absolute path for Excel files 
my Sexcel_file = abs_path("SExcel_path") or die "Error: the file $Excel_path has not been found\n"; 


# Open Excel application 
my SExcel = Win32::OLE->GetActiveObject('Excel.Application' ) 
|| Win32::OLE->new('Excel.Application', ‘Quit'); 


# Open Excel file 
my SBook = SExcel->Workbooks->0pen(Sexcel_file) ; 


#Make Excel visible 
SExcel->{Visible} = 1; 


#___ ADD NEW WORKBOOK 
my $Book = SExcel->Workbooks->Add; 
my $Sheet = SBook->Worksheets("Sheet1") ; 


SSheet->Activate; 
#Save Excel file 
SExcel->{DisplayAlerts}=0; # This turns off the "This file already exists" message. 


SBook->Save; #0r SBook->SaveAs("C:\\file_name.xl1s") ; 
SBook->Close; #or SExcel->Quit; 


Section 28.2: Manipulation of Worksheets 


#Get the active Worksheet 
my $Book = SExcel->Activewindow; 
my $Sheet = $Book->Activesheet ; 


#List of Worksheet names 
my @list_Sheet = map { $_->{'Name'} } (in SBook->{Worksheets}) ; 


#Access a given Worksheet 
my $Sheet = SBook->Worksheets(Slist_Sheet[@]); 


#Add new Worksheet 
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SBook->Worksheets->Add( {After => Sworkbook->Worksheets(Sworkbook->Worksheets->{Count})}) ; 


#Change Worksheet Name 
SSheet->{Name} = "Name of Worksheet"; 


#Freeze Pane 
SExcel -> ActiveWindow -> {FreezePanes} = "True"; 


#Delete Sheet 
SSheet -> Delete; 


Section 28.3: Manipulation of cells 


#Edit the value of a cell (2 methods) 
SSheet->Range("A1")->{Value} = 1234; 
SSheet->Cells(1,1)->{Value} = 1234; 


#Edit the values in a range of cells 
SSheet->Range("A8:C9")->{Value} = [[ undef, ‘Xyzzy', 
[| 42, ‘Perl. 3.9415 


"Plugh' J, 
l1; 


#Edit the formula in a cell (2 types) 
$Sheet->Range("A1")->{Formula} = "=A1*9.81"; 
SSheet->Range("A3")->{FormulaR1C1} = "“=SUM(R[-2]C:R[-1]C)"; 
$Sheet->Range("C1")->{FormulaR1C1} = "“=SUM(RC[-2]:RC[-1])"; 


# Sum of rows 


#Edit the format of the text (font) 


$Sheet->Range("G7:H7" )->Font->{Bold} = "True"; 
SSheet->Range("G7:H7" )->Font->{Italic} = "True"; 
$Sheet->Range("G7:H7 xlUnderlineStyleSingle; 


:H7")->Font->{Size} = 8; 
:H7" )->Font->{Name } > Arial 
:H7")->Font->{ColorIndex} = 4; 


$Sheet->Range("G7 


) 

) 
")->Font->{Underline} = 

) 

) 

"G7 ) 


( 
( 
$Sheet->Range ("G7 
( 
SSheet->Range( 


#Edit the number format 


Sheet -> Range("G7:H7") -> {NumberFormat} = "\@"; 

SSheet -> Range("A1:H7") -> {NumberFormat} = "\S#,##@.00"; 

Sheet -> Range("G7:H7") -> {NumberFormat} = "\S#,##0.00_);[Red](\S#, ##0.00)"; 
negatives 

$Sheet -> Range("G7:H7") -> {NumberFormat} = "@.0@_);[Red](0.00)"; 

decimals 

Sheet -> Range("G7:H7") -> {NumberFormat} = "#,##0"; # 
commas 

Sheet -> Range("G7:H7") -> {NumberFormat} = "#,##0_);[Red] (#,##0)"; 

commas - red negatives 

$Sheet -> Range("G7:H7") -> {NumberFormat} = "0.00%"; 

Sheet -> Range("G7:H7") -> {NumberFormat} = “m/d/yyyy" 

#Align text 

Sheet -> Range("G7:H7") -> {HorizontalAlignment} = xlHAlignCenter; 

Sheet -> Range("A1:A2") -> {Orientation} = 90; 


#Activate Cell 
Sheet -> Range("A2") -> Activate; 


$Sheet->Hyperlinks->Add({ 


# Sum of columns 


# Text 
# Currency 
# Currency - red 
# Numbers with 
Numbers with 
# Numbers with 
# Percents 


# Dates 


# Center text; 
# Rotate text 


Anchor => range, #Range of cells with the hyperlink; e.g. SSheet->Range("A1") 
Address => Sadr, #File path, http address, etc. 

TextToDisplay => Stxt, #Text in the cell 

ScreenTip => tip, #Tip while hovering the mouse over the hyperlink 
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DE 





N.B: to retrieve the list of hyperlinks, have a look at the following post Getting list of hyperlinks from an Excel 
worksheet with Perl Win32::OLE 





Section 28.4: Manipulation of Rows / Columns 


#Insert a row before/after line 22 
$Sheet->Rows("22:22")->Insert(xlUp, xlFormatFromRightOrBelow) ; 
$Sheet->Rows("23:23")->Insert(-4121,8); #x1Down is -4121 and that xlFormatFromLeftOrAbove is @ 


#Delete a row 
$Sheet->Rows("22:22")->Delete() ; 


#Set column width and row height 

Sheet -> Range('A:A') -> {ColumnWidth} = 9.14; 
SSheet -> Range("8:8") -> {RowHeight} = 30; 
Sheet -> Range("G:H") -> {Columns} -> Autofit; 


# Get the last row/column 

my Slast_row = $Sheet -> UsedRange -> Find({What => "*", SearchDirection => xlPrevious, SearchOrder 
=> x1ByRows}) -> {Row}; 

my Slast_col = $Sheet -> UsedRange -> Find({What => "*", SearchDirection => xlPrevious, SearchOrder 
=> xlByColumns}) -> {Column}; 


#Add borders (method 1) 


Sheet -> Range("A3:H3") -> Borders(xlEdgeBottom) -> {LineStyle} = xlDouble; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeBottom) -> {Weight} = xlThick; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeBottom) -> {ColorIndex} = 1; 

Sheet -> Range("A3:H3") -> Borders(xlEdgeLeft) -> {LineStyle} = xlContinuous; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeLeft) -> {Weight} = xlThin; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeTop) -> {LineStyle} = xlContinuous; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeTop) -> {Weight} = xlThin; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeBottom) -> {LineStyle} = xlContinuous; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeBottom) -> {Weight} = xlThin; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeRight) -> {LineStyle} = xlContinuous; 
Sheet -> Range("A3:H3") -> Borders(xlEdgeRight) -> {Weight} = xlThin; 
Sheet -> Range("A3:H3") -> Borders(xlInsideVertical) -> {LineStyle} = xlDashDot 
Sheet -> Range("A3:H3") -> Borders(xlInsideVertical) -> {Weight} = xlMedium; 
Sheet -> Range("A3:I3") -> Borders(xlInsideHorizontal) -> {LineStyle} = xlContinuous; 
Sheet -> Range("A3:I3") -> Borders(xlInsideHorizontal) -> {Weight} = xlThin; 


#Add borders (method 2) 
my @edges = qw (xlInsideHorizontal xlInsideVertical xlEdgeBottom xlEdgeTop xlEdgeRight) ; 
foreach my $edge (@edges) 
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Chapter 29: Simple interaction with 
database via DBI module 


Column Column 
Sdriver Driver for DB, "Pg" for Postgresql and "mysql" for MySQL 


Sdatabase your database name 

Suserid your database id 

Spassword your database password 

$query — put your query here, ex: "select * from $your_table" 


Section 29.1: DBI module 


You should make sure that module DBI has been installed on your pc, then follow the bellow steps: 
1. use DBI module in your perl script 

use DBI; 
2. Declare some primary parameters 

my Sdriver = "“MyDriver"; 

my Sdatabase = "DB_name"; 

my Sdsn = "DBI:Sdriver :dbname=Sdatabase" ; 

my Suserid = "“your_user_ID"; 

my Spassword = "“your_password'"; 

my Stablename = "“your_table"; 
3. Connect to your database 

my Sdbh = DBI->connect($dsn, Suserid, Spassword) ; 
4. Prepare your query 

my $query = Sdbh->prepare("Your DB query"); 

Ex: 


Smy_query = gq/SELECT * FROM table WHERE column1 = 2/; 


my $query = Sdbh->prepare(Smy_query) ; 

We can also use variable in the query, like below: 

my Stable_name = "table"; 

my S$filter_value = 2; 

Smy_query = qq/SELECT * FROM Stable_name WHERE column1 = Sfilter_value/; 
5. Execute your query 


Squery->execute(); 
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*Note: To avoid injection attack, you should use placeholders ? instead of put your variable in the query. 


Ex: you want to show the all data from 'table' where column1=$value1 and column2=$value2: 
my $query = $dbh->prepare( "SELECT * FROM table WHERE column1 = ? AND column2 = ?;"); 


Squery->execute(Svalue1, Svalue2); 
6. Fletch your data 
my @row = Squery->fetchrow_array(); store data as array 
or 
my Sref = Ssth->fetchrow_hashref() ; store data as hash reference 


7. Finish and disconnect DB 
Ssth->finish; 


Sdbh->disconnect(); 
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Chapter 30: Perl Testing 


Section 30.1: Perl Unit Testing Example 


The following is a simple example Perl test script, that gives some structure to allow for testing of other methods 
the class/package under test. The script produces standard output with simple "ok" / "not ok" text, which is called 
TAP (Test Anything Protocol). 


Typically the prove command runs the script(s) and summarises the test results. 


#!/bin/env perl 

# CPAN 

use Modern: :Perl; 
use Carp; 

use Test: :More; 

use Test: :Exception; 
use Const: :Fast; 


# Custom 
BEGIN { use_ok('Local::MyPackage'); } 


const my SPACKAGE_UNDER_TEST => ‘Local: :MyPackage' ; 


# Example test of method 'file_type_build' 
sub test_file_type_build { 
my %arg = @_; 
my S$label = 'file_type_build' ; 
my S$got_file_type; 
my $filename = '/etc/passwd'; 


# Check the method call lives 
lives_ok( 
sub { 
Sgot_file_type = SPACKAGE_UNDER_TEST->file_type_build( 
filename => $filename 
ye 
} 


label - lives" 


yi 


# Check the result of the method call matches our expected result. 
like( Sgot_file_type, qr{ASCII[ ]text}ix, "Slabel - result" ); 
return; 

} ## end sub test_file_type_build 


# More tests can be added here for method 'file_type_build', or other methods. 


MAIN: { 


subtest 'file_type_build' => sub { 
test_file_type_build() ; 
# More tests of the method can be added here. 
done_testing() ; 


E 


# Tests of other methods can be added here, just like above. 
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done_testing() ; 
} ## end MAIN: 


Best Practice 
A test script should only test one package/class, but there many scripts may be used to test a package/class. 
Further Reading 


e Test::More - The basic test operations. 

e Test::Exception - Testing thrown exceptions. 

e Test::Differences - Comparing test results that have complex data structures. 
e Test::Class - Class based testing rather than script. Similarities to JUnit. 

Perl Testing Tutorials - Further reading. 








Goalkicker.com - Perl® Notes for Professionals 


88 


Chapter 31: Dancer 


About: 
Dancer2 (the successor of Dancer) is a simple but powerful web application framework for Perl. 
It is inspired by Sinatra and written by Alexis Sukrieh. 


Key features: *** Dead Simple - Intuitive, minimalist and very expressive syntax. *** Flexible - PSG! support, plugins 
and modular design allow for strong scalability. ««* Few dependencies - Dancer depends on as few CPAN modules 
as possible making it easy to install. 


Section 31.1: Easiest example 


#!/usr/bin/env perl 
use Dancer2; 


get '/' => sub { 
"Hello World!" 
i 


dance; 
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Chapter 32: Attributed Text 


Section 32.1: Printing colored Text 
#!/usr/bin/perl 
use Term: :ANSIColor; 


print color("cyan"), "Hello", color("red"), 


"\tWorld", color("green"), 
color("reset"); 


Hello World It's Me! 
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Chapter 33: GUI Applications in Perl 
Section 33.1: GTK Application 


use strict; 
use warnings; 


use Gtk2 -init; 


my Swindow = Gtk2: :Window->new() ; 
Swindow->show() ; 


Gtk2->main(); 


Q; 
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Chapter 34: Memory usage optimization 


Section 34.1: Reading files: foreach vs. while 


When reading a potentially large file, a while loop has a significant memory advantage over foreach. The following 
will read the file record by record (by default, "record" means "a line", as specified by $/), assigning each one to $_ 
as it is read: 


while(<Sfh>) { 
print; 


} 


The diamond operator does some magic here to make sure the loop only terminates at end-of-file and not e.g. on 
lines that contain only a "0" character. 


The following loop seems to work just the same, however it evaluates the diamond operator in list context, causing 
the entire file to be read in one go: 


foreach(<Sfh>) { 
print; 


} 


If you are operating on one record at a time anyway, this can result in a huge waste of memory and should thus be 
avoided. 


Section 34.2: Processing long lists 


If you have a list in memory already, the straightforward and usually sufficient way to process it is a simple foreach 
loop: 


foreach my Sitem (@items) { 


} 


This is fine e.g. for the common case of doing some processing on $item and then writing it out to a file without 
keeping the data around. However, if you build up some other data structure from the items, a while loop is more 
memory efficient: 


my @result; 
while(@items) { 
my $item = shift @items; 
push @result, process_item(Sitem) ; 


Unless a reference to $item directly ends up in your result list, items you shifted off the @items array can be freed 
and the memory reused by the interpreter when you enter the next loop iteration. 
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Chapter 35: Perl script debugging 


Section 35.1: Run script in debug mode 

To run script in debug mode you should add -d option in the command line: 

Sperl -d script.pl 

If t is specified, it indicates to the debugger that threads will be used in the code being debugged: 
Sperl -dt script.pl 

Additional info at perldocperlrun 


Section 35.2: Use a nonstandard debugger 


Sperl -d:MOD script.pl runs the program under the control of a debugging, profiling, or tracing module installed 
as Devel: :MOD. 


For example, -d:NYTProf executes the program using the Devel: :NYTProf profiler. 





See all available Devel modules here 





Recommended modules: 


e Devel: :NYTProf -- Powerful fast feature-rich Perl source code profiler 

e Devel: :Trepan -- A modular gdb-like Perl debugger 

e Devel: :MAT -- Perl Memory Analysis Tool 

e Devel: :hdb -- Perl debugger as a web page and REST service 

e Devel: :DebugHooks: :Kil1Print -- Allows to forget about debugging by print statement 
e Devel: :REPL -- A modern perl interactive shell 

e Devel: :Cover -- Code coverage metrics for Perl 
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Chapter 36: Perlbrew 


Perlbrew is a tool to manage multiple perl installations in your SHOME directory. 


Section 36.1: Setup perlbrew for the first time 


Create setup Script ~/.perlbrew. sh: 


# Reset any environment variables that could confuse ‘perlbrew’: 
export PERL_LOCAL_LIB_ROOT= 

export PERL_MB_OPT= 

export PERL_MM_OPT= 


# decide where you want to install perlbrew: 
export PERLBREW_ROOT=~/perlbrew 
[[ -f "SPERLBREW_ROOT/etc/bashrc" ]] && source "SPERLBREW_ROOT/etc/bashrc" 


Create installation script install_perlbrew. sh: 


source ~/.perlbrew.sh 
curl -L https://install.perlbrew.pl | bash 
source "SPERLBREW_ROOT/etc/bashrc" 


# Decide which version you would like to install: 
version=perl-5.24.1 

perlbrew install "Sversion" 

perlbrew install-cpanm 

perlbrew switch "Sversion" 


Run installation script: 
./install_perlbrew.sh 


Add to the end of your ~/ .bashrc 
[| -f ~/.perlbrew.sh ]] && source ~/.perlbrew.sh 


Source ~/ .bashrc: 


source ~/.bashre 
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Chapter 37: Installation of Perl 


I'm going to begin this with the process in Ubuntu, then in OS X and finally in Windows. | haven't tested it on all perl 
versions, but it should be a similar process. 


Use Perlbrew if you like to switch easily beween different versions of Perl. 


| want to state that this tutorial is about Perl in it's open-source version. There are other versions like activeperl 
which its advantages and disadvantages, that are not part of this tutorial. 


Section 37.1: Linux 


There is more than one way to do it: 


e Using the package manager: 


sudo apt install perl 


e Installing from source: 


wget http://ww.cpan.org/src/5.0/perl-version.tar.gz 
tar -xzf perl-version.tar.gz 

cd perl-version 

./Configure -de 

make 

make test 

make install 


e Installing in your $home directory (not sudo needed) with Perlbrew: 


wget -0 - https://install.perlbrew.pl | bash 


See also Perlbrew 


Section 37.2: OS X 


There are several options: 


e Perlbrew: 


# You need to install Command Line Tools for Xcode 
curl -L https://install.perlbrew.pl | bash 


e Perlbrew with thread support: 


# You need to install Command Line Tools for Xcode 
curl -L https://install.perlbrew.pl | bash 


After the install of perlbrew, if you want to install Perl with thread support, just run: 


perlbrew install -v perl-5.26.@ -Dusethreads 
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e From source: 


tar -xzf perl-version.tar.gz 
cd perl-version 

./Configure -de 

make 

make test 

make install 


Section 37.3: Windows 


e As we Said before, we go with the open-source version. For Windows you can choose strawberry or DWIM. 
Here we cover the strawberry version, since DWIM is based on it. The easy way here is installing from the 
official executable. 





See also berrybrew - the perlbrew for Windows Strawberry Perl 
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Chapter 38: Compile Perl coan module 
sapnwrfc from source code 


I'd like to describe the prerequisites and the steps how to build the Perl CPAN module sapnwrfc with the Strawberry 
Perl environment under Windows 7 x64. It should work also for all later Windows versions like 8, 8.1 and 10. 


| use Strawberry Perl 5.24.1.1 64 bit but it should also work with older versions. 


It took me some hourse to succeed with several tries (32 vs. 64 bit installation of Perl, SAP NW RFC SDK, MinGW vs. 
Microsoft C compiler). So | hope some will benefit from my findings. 


Section 38.1: Simple example to test the RFC connection 


Simple example from http://search.cpan.org/dist/sapnwrfc/sapnwrfc-cookbook.pod 





use strict; 
use warnings; 
use utf8; 

use sapnwrfc; 


SAPNW: :Rfc->load_config('sap.ym1' ); 
my Sconn = SAPNW: :Rfc->rfc_connect; 


my Srd = Sconn->function_lookup("RPY_PROGRAM_READ") ; 
my $rc = S$rd->create_function_call; 
Src->PROGRAM_NAME ("SAPLGRFC") ; 


eval { 
Src->invoke; 
Pe 
if ($@) { 
die "RFC Error: S@\n"; 
} 


print "Program name: ".$rc->PROG_INF->{'PROGNAME'}."\n"; 


my Scnt_lines_with_text = scalar grep(/LGRFCUXX/, map { $_->{LINE} } @{$rc->SOURCE_EXTENDED}) ; 
Sconn->disconnect; 
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Chapter 39: Best Practices 
Section 39.1: Using Perl::Critic 


If you'd like to start implementing best practices, for yourself or your team, then Perl::Critic is the best place to start. 
The module is based on the Perl Best Practices book by Damien Conway and does a fairly good job implementing the 
suggestions made therein. 





Note: / should mention (and Conway himself says in the book) that these are suggestions. I've found the book 
provides solid reasoning in most cases, though I certainly don't agree with all of them. The important thing to 

remember is that, whatever practices you decide to adopt, you remain consistent. The more predictable your 

code is, the easier it will be to maintain. 


You can also try out Perl::Critic through your browser at perlcritic.com. 


Installation 


cpan Perl: :Critic 


This will install the basic ruleset and a perlcritic script that can be called from the command line. 


Basic Usage 


The CPAN doc for perlcritic contains full documentation, so | will only be going over the most common use cases to 
get you Started. Basic usage is to simply call perlcritic on the file: 





perlcritic -1 /path/to/script.pl 


perlcritic works both on scripts and on modules. The -1 refers to the severity level of the rules you want to run 
against the script. There are five levels that correspond to how much Perl::Critic will pick apart your code. 


-5 is the most gentle and will only warn about potentially dangerous problems that could cause unexpected results. 
-1 is the most brutal and will complain about things as small as your code being tidy or not. In my experience, 
keeping code compliant with level 3 is good enough to keep out of danger without getting too persnickety. 


By default, any failures will list the reason and severity the rule triggers on: 


perlcritic -3 --verbose 8 /path/to/script.pl 


Debugging module loaded at line 16, column 1. You've loaded Data::Dumper, which probably shouln't 
be loaded in production. (Severity: 4) 

Private subroutine/method '_sub_name' declared but not used at line 58, column 1. Eliminate dead 
code. (Severity: 3) 

Backtick operator used at line 239, column 37. Use IPC::Open3 instead. (Severity: 3) 

Backtick operator used at line 327, column 22. Use IPC::Open3 instead. (Severity: 3) 


Viewing Policies 
You can quickly see which rules are being triggered and why by utilizing perlcritic's --verbose option: 


Setting the level to 8 will show you the rule that triggered a warning: 
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perlcritic -3 --verbose 8 /path/to/script.pl 


| Bangs: :ProhibitDebuggingModules] Debugging module loaded at line 16, column 1. (Severity: 4) 

[| Subroutines: :ProhibitUnusedPrivateSubroutines] Private subroutine/method '_sub_name' declared but 
not used at line 58, column 1. (Severity: 3) 

| InputOutput: :ProhibitBacktickOperators] Backtick operator used at line 230, column 37. (Severity: 
3) 

| InputOutput: :ProhibitBacktickOperators] Backtick operator used at line 327, column 22. (Severity: 
3) 


While a level of 11 will show the specific reasons why the rule exists: 


perlcritic -3 --verbose 11 /path/to/script.pl 


Debugging module loaded at line 16, near ‘use Data::Dumper;’. 
Bangs: :ProhibitDebuggingModules (Severity: 4) 
This policy prohibits loading common debugging modules like the 
Data: :Dumper manpage. 


While such modules are incredibly useful during development and 
debugging, they should probably not be loaded in production use. If this 
policy is violated, it probably means you forgot to remove a “use 
Data: :Dumper;' line that you had added when you were debugging. 

Private subroutine/method '_svn_revisions_differ' declared but not used at line 58, near ‘sub 

_sub_name {'. 

Subroutines: :ProhibitUnusedPrivateSubroutines (Severity: 3) 

By convention Perl authors (like authors in many other languages) 
indicate private methods and variables by inserting a leading underscore 
before the identifier. This policy catches such subroutines which are 
not used in the file which declares them. 


This module defines a ‘use’ of a subroutine as a subroutine or method 
call to it (other than from inside the subroutine itself), a reference 
to it (i.e. “my $foo = \&_foo'), a ‘goto’ to it outside the subroutine 
itself (i.e. ‘goto &_foo'), or the use of the subroutine's name as an 
even-numbered argument to “use overload’. 
Backtick operator used at line 230, near ‘my S$filesystem_diff = join q{}, “diff Strunk_checkout 
Sstaging_checkout~*;'. 
InputOutput : :ProhibitBacktickOperators (Severity: 3) 
Backticks are super-convenient, especially for CGI programs, but I find 
that they make a lot of noise by filling up STDERR with messages when 
they fail. I think its better to use IPC::Open3 to trap all the output 
and let the application decide what to do with it. 


use IPC::Open3 ‘open3' ; 
SSIG{CHLD} = ‘IGNORE’; 


@output = ~some_command’ ; #not ok 


my (Swriter, Sreader, Serr); 

open3(Swriter, Sreader, Serr, '‘some_command'); #ok; 

@output = <Sreader>; #Output here 

@errors = <Serr>; #Errors here, instead of the console 

Backtick operator used at line 327, near ‘my $output = `$cmd`;'. 
InputOutput: :ProhibitBacktickOperators (Severity: 3) 

Backticks are super-convenient, especially for CGI programs, but I find 
that they make a lot of noise by filling up STDERR with messages when 
they fail. I think its better to use IPC::Open3 to trap all the output 
and let the application decide what to do with it. 


use IPC::Open3 ‘open3' ; 
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SSIG{CHLD} = 'IGNORE' ; 

@output = ~some_command’ ; #not ok 
my (Swriter, Sreader, Serr); 

open3(Swriter, Sreader, Serr, '‘some_command'); #ok; 


@output = <Sreader>; #Output here 
@errors = <Serr>; #Errors here, instead of the console 


Ignoring Code 


There will be times when you can't comply with a Perl::Critic policy. In those cases, you can wrap special comments, 
"## use critic()" and "## no critic", around your code to make Perl::Critic ignore them. Simply add the rules you 
want to ignore in the parentheses (multiples can be separated by a comma). 


##no critic qw(InputOutput: :ProhibitBacktickOperator) 
my S$filesystem_diff = join q{}, “diff $trunk_checkout Sstaging_checkout’ ; 
## use critic 


Make sure to wrap the entire code block or Critic may not recognize the ignore statement. 


## no critic (Subroutines: :ProhibitExcessComplexity) 
sub no_time_to_refactor_this { 


} 


## use critic 


Note that there are certain policies that are run on the document level and cannot be exempted this way. However, 
they can be turned off... 


Creating Permanent Exceptions 


Using ## no critic() is nice, but as you start to adopt coding standards, you will likely want to make permanent 
exceptions to certain rules. You can do this by creating a .perlcriticre configuration file. 


This file will allow you to customize not only which policies are run, but how they are run. Using it is as simple as 
placing the file in your home directory (in Linux, unsure if it's the same place on Windows). Or, you can specify the 
config file when running the command using the --profile option: 


perlcritic -1 --profile=/path/to/.perlcriticre /path/to/script.pl 


Again, the perlcritic CPAN page has a full list of these options. | will list some examples from my own config file: 





Apply basic settings: 


#very very harsh 

severity = 1 

color-severity-medium = bold yellow 
color-severity-low = yellow 
color-severity-lowest = bold blue 


Disable a rule (note the dash in front of the policy name): 


# do not require version control numbers 
| -Miscellanea: :RequireRcsKeywords ] 
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# pod spelling is too over-zealous, disabling 
| -Documentation: :PodSpelling] 


Modifying a rule: 
# do not require checking for print failure ( false positives for printing to stdout, not filehandle 
) 


| InputOutput : :RequireCheckedSyscalls | 
functions = open close 


# Allow specific unused subroutines for moose builders 


[ Subroutines: :ProhibitUnusedPrivateSubroutines | 
private_name_regex = _(?!build_)\w+ 


Conclusion 


Properly utilized, Perl::Critic can be an invaluable tool to help teams keep their coding consistent and easily 
maintainable no matter what best practice policies you employ. 
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